Pi Agent Keyboard Shortcut Customization

Pi Agent's shortcuts are fully customizable. This chapter introduces the default shortcut configuration and how to create your own shortcut scheme.

Configuration File

The shortcut configuration file is located at~/.pi/agent/keybindings.json。

After modification, run/reloadto take effect without restarting.

Shortcut Format

The shortcut format isModifier+KeyModifier keys include ctrl, shift, alt, and super, which can be combined.

Among them, super only works if the terminal can report this modifier key separately (usually relying on the Kitty keyboard protocol); it may not work in unsupported terminals.

Supported keys are divided into the following categories:

In the configuration file, modifier keys are written in lowercase (e.g., ctrl+shift+p), while tables in the text are usually written as Shift+Ctrl+P; the two are equivalent.

Default Shortcut Quick Reference

The following four tables list the factory default bindings by functional area, serving as a baseline for customization.

This chapter only lists common bindings; ctrl+], ctrl+alt+], pageUp/pageDown, alt+y, ctrl+z, and session selector keys are not included. The full list can be viewed with /hotkeys in interactive mode.

Editor Operations

This group only takes effect in the editor area, handling cursor movement and text deletion.

Input and Submission

This group controls how content is wrapped, completed, and submitted, and also applies to the editor area.

Application and Messages

This group is responsible for interrupting the AI, managing editor content and the message queue, and mostly does not depend on editor focus.

Model and Reasoning

This group is used to switch models and adjust reasoning behavior, and is available at any time during a conversation.

Custom Shortcut Configuration

Simply list the operations you want to override in keybindings.json; operations not listed retain their defaults.

Set a binding's value to an empty array, for example"tui.altScreen.pageUp": []to completely disable that shortcut.

Emacs Style

If you are used to Emacs shortcuts, you can~/.pi/agent/keybindings.jsonuse the following configuration in:

The two history actions historyPrevious and historyNext are not bound by default; they are specifically for browsing submission history, and they also switch history entries in multiline input.

After binding ctrl+p to the previous history item, when the editor area gains focus, Ctrl+P will be preempted by this history binding, and forward model switching temporarily becomes ineffective in this scenario.

Ctrl+P in selection lists such as the model selector is not affected and still performs the selector's own action.

Vim Style

If you are used to Vim's arrow keys, you can use the following configuration:

Here, alt+h/j/k/l are chosen to avoid built-in bindings such as Ctrl+H and Ctrl+D, so the Alt series is used.

Pi Agent's shortcut configuration overrides the default values.

Each operation can be bound to one or more shortcuts.

Operations not listed in the configuration file retain their default shortcuts.

View All Shortcuts

In interactive mode, use the following command to display all shortcuts and their current bindings:

/hotkeys

Example output:

编辑器
  tui.editor.cursorUp            up
  tui.editor.cursorDown          down
  tui.editor.cursorWordLeft      alt+left, ctrl+left, alt+b
  tui.input.submit               enter
模型与推理
  app.model.select               ctrl+l
  app.model.cycleForward         ctrl+p
  app.model.cycleBackward        shift+ctrl+p

Shortcut operations use namespaced IDs in the format "module.action".

IDs without namespaces in older config files (such as cursorUp, expandTools) will be automatically migrated to namespaced IDs at startup; no manual modification required.

This command lists all available shortcut actions, current bindings, and their associated feature areas, making it the best way to troubleshoot keybinding conflicts or find the shortcut for a specific feature.

Keys in Fullscreen Mode

use--tui-mode fullscreenAt startup, the transcript scrolls within the terminal viewport, while the editor and bottom status area remain fixed.

At this point, home, end, pageUp, and pageDown without modifier keys are used to scroll the transcript, while their ctrl variants still belong to the editor.

In normal mode, both sets of keys act on the editor.

Fullscreen mode also has dedicated search and navigation: ctrl+shift+f searches the transcript, and ctrl+up / ctrl+down jump between the previous and next marked messages.

Fullscreen scroll bindings take precedence over editor bindings and can still be adjusted through normal action bindings.