Keybindings Reference
Pi exposes named actions, such as app.session.new, that can be assigned keybindings. You can change default assignments or bind unassigned actions in Pi's user configuration.
Run /hotkeys to see the active shortcuts for the main editor and application.
Assign keybindings
Create <agent-dir>/keybindings.json. The agent directory defaults to ~/.pi/agent and is described in Agent directory.
Map each action identifier to one key or a list of keys:
{
"app.session.new": "ctrl+shift+n",
"app.session.tree": ["ctrl+shift+t", "alt+shift+t"]
}A configured value replaces the default for that action. Use an empty list to disable an action's keybindings:
{
"tui.altScreen.pageUp": []
}After editing the file, run /reload to apply the changes to the active session.
Key syntax
Write a key as modifier+key. Modifiers are ctrl, shift, alt, and super. You can combine modifiers. Valid keys are:
- Letters:
a-z - Digits:
0-9 - Special:
escape,esc,enter,return,tab,space,backspace,delete,insert,clear,home,end,pageUp,pageDown,up,down,left,right - Function:
f1-f12 - Symbols:
`,-,=,[,],\,;,',,,.,/,!,@,#,$,%,^,&,*,(,),_,+,|,~,,,:,<,>,?
Examples: ctrl+shift+x, alt+ctrl+x, ctrl+shift+alt+x, super+k, ctrl+super+k, and ctrl+1.
super bindings require a terminal that reports the modifier separately, typically through the Kitty keyboard protocol. They may not work in terminals without that support.
Actions
Terminal UI
Cursor movement
| Keybinding id | Default | Description |
|---|---|---|
tui.editor.cursorUp | up | Move cursor up, browsing older history at the top |
tui.editor.cursorDown | down | Move cursor down, browsing newer history at the bottom |
tui.editor.historyPrevious | None | Select the previous prompt history entry |
tui.editor.historyNext | None | Select the next prompt history entry |
tui.editor.cursorLeft | left, ctrl+b | Move cursor left |
tui.editor.cursorRight | right, ctrl+f | Move cursor right |
tui.editor.cursorWordLeft | alt+left, ctrl+left, alt+b | Move cursor word left |
tui.editor.cursorWordRight | alt+right, ctrl+right, alt+f | Move cursor word right |
tui.editor.cursorLineStart | home, ctrl+a | Move to line start |
tui.editor.cursorLineEnd | end, ctrl+e | Move to line end |
tui.editor.jumpForward | ctrl+] | Jump forward to character |
tui.editor.jumpBackward | ctrl+alt+] | Jump backward to character |
tui.editor.pageUp | pageUp, ctrl+pageUp | Scroll up by page |
tui.editor.pageDown | pageDown, ctrl+pageDown | Scroll down by page |
The dedicated history actions browse prompt history regardless of cursor position and take precedence over application actions using the same key.
Text editing
| Keybinding id | Default | Description |
|---|---|---|
tui.editor.deleteCharBackward | backspace | Delete character backward |
tui.editor.deleteCharForward | delete, ctrl+d | Delete character forward |
tui.editor.deleteWordBackward | ctrl+w, alt+backspace | Delete word backward |
tui.editor.deleteWordForward | alt+d, alt+delete | Delete word forward |
tui.editor.deleteToLineStart | ctrl+u | Delete to line start |
tui.editor.deleteToLineEnd | ctrl+k | Delete to line end |
tui.editor.yank | ctrl+y | Paste most recently deleted text |
tui.editor.yankPop | alt+y | Cycle through deleted text after yank |
tui.editor.undo | ctrl+- (ctrl+z on Windows; alt+z on WSL) | Undo last edit |
Input and selection
| Keybinding id | Default | Description |
|---|---|---|
tui.input.newLine | shift+enter, ctrl+j | Insert new line |
tui.input.submit | enter | Submit input |
tui.input.tab | tab | Tab or autocomplete |
tui.input.copy | ctrl+c | Copy selection |
tui.select.up | up | Move selection up |
tui.select.down | down | Move selection down |
tui.select.pageUp | pageUp | Page up in list |
tui.select.pageDown | pageDown | Page down in list |
tui.select.confirm | enter | Confirm selection |
tui.select.cancel | escape, ctrl+c | Cancel selection |
Fullscreen
In fullscreen mode, these actions control the transcript and take precedence over editor actions using the same key.
| Keybinding id | Default | Description |
|---|---|---|
tui.altScreen.pageUp | pageUp | Scroll the transcript up by one page |
tui.altScreen.pageDown | pageDown | Scroll the transcript down by one page |
tui.altScreen.halfPageUp | None | Scroll the transcript up by half a page |
tui.altScreen.halfPageDown | None | Scroll the transcript down by half a page |
tui.altScreen.lineUp | None | Scroll the transcript up by one line |
tui.altScreen.lineDown | None | Scroll the transcript down by one line |
tui.altScreen.previousPrompt | ctrl+shift+up, ctrl+up (ctrl+up only on Windows and WSL) | Jump to the previous marked message |
tui.altScreen.nextPrompt | ctrl+shift+down, ctrl+down (ctrl+down only on Windows and WSL) | Jump to the next marked message |
tui.altScreen.search | ctrl+shift+f (ctrl+f on Windows and WSL) | Search the rendered transcript |
tui.altScreen.searchNext | enter, ctrl+g | Select the next search match while searching |
tui.altScreen.searchPrevious | shift+enter, ctrl+shift+g | Select the previous search match while searching |
tui.altScreen.searchClose | escape | Close transcript search |
tui.altScreen.top | ctrl+home | Scroll to the beginning of the transcript |
tui.altScreen.bottom | ctrl+end | Scroll to the transcript end and follow new output |
Application
| Keybinding id | Default | Description |
|---|---|---|
app.interrupt | escape | Cancel / abort |
app.clear | ctrl+c | Clear editor (first) / exit (second) |
app.exit | ctrl+d | Exit (when editor empty) |
app.suspend | ctrl+z (None on Windows) | Suspend to background |
app.editor.external | ctrl+g | Open in external editor (externalEditor, $VISUAL, $EDITOR, Notepad on Windows, or nano elsewhere) |
app.clipboard.pasteImage | ctrl+v (alt+v on Windows and WSL) | Paste files on macOS, images, or text from clipboard |
On native Windows, app.suspend has no default because Windows terminals do not support Unix job control. If you assign it manually, Pi shows a status message instead of suspending. WSL uses the normal ctrl+z and fg behavior.
Sessions
| Keybinding id | Default | Description |
|---|---|---|
app.session.new | None | Start a new session (/new) |
app.session.tree | None | Open session tree navigator (/tree) |
app.session.fork | None | Fork current session (/fork) |
app.session.resume | None | Open session resume picker (/resume) |
app.session.togglePath | ctrl+p | Toggle path display |
app.session.toggleSort | ctrl+s | Toggle sort mode |
app.session.toggleNamedFilter | ctrl+n | Toggle named-only filter |
app.session.rename | ctrl+r | Rename session |
app.session.delete | ctrl+d | Delete session |
app.session.deleteNoninvasive | ctrl+backspace | Delete session when query is empty |
Models and Thinking
| Keybinding id | Default | Description |
|---|---|---|
app.model.select | ctrl+l | Open model selector |
app.model.cycleForward | ctrl+p | Cycle to next model |
app.model.cycleBackward | shift+ctrl+p (alt+p on Windows and WSL) | Cycle to previous model |
app.models.save | ctrl+s | Save the selected default model or scoped model configuration to settings |
app.thinking.cycle | shift+tab | Cycle thinking level |
app.thinking.save | ctrl+s | Save current thinking level to settings |
app.thinking.toggle | ctrl+t | Collapse or expand thinking blocks |
Display and Message Queue
| Keybinding id | Default | Description |
|---|---|---|
app.tools.expand | ctrl+o | Collapse or expand tool output |
app.message.copy | ctrl+x | Copy the selected message in /tree; in fullscreen mode, copy the active selection when fullscreenCopyOnSelect is false; otherwise copy the last assistant message. On OAuth sign-in screens, copy the sign-in URL |
app.message.followUp | alt+enter (ctrl+q on Windows and WSL) | Queue follow-up message |
app.message.dequeue | alt+up (alt+q on Windows and WSL) | Restore queued messages to editor |
Tree Navigation
| Keybinding id | Default | Description |
|---|---|---|
app.tree.foldOrUp | ctrl+left, alt+left | Fold current branch segment, or jump to the previous segment start |
app.tree.unfoldOrDown | ctrl+right, alt+right | Unfold current branch segment, or jump to the next segment start or branch end |
app.tree.editLabel | shift+l | Edit the label on the selected tree node |
app.tree.toggleLabelTimestamp | shift+t | Toggle label timestamps in the tree |
app.tree.filter.default | ctrl+d | Set tree filter to default view |
app.tree.filter.noTools | ctrl+t | Toggle tree filter that hides tool results |
app.tree.filter.userOnly | ctrl+u | Toggle tree filter that shows only user messages |
app.tree.filter.labeledOnly | ctrl+l | Toggle tree filter that shows only labeled entries |
app.tree.filter.all | ctrl+a | Toggle tree filter that shows all entries |
app.tree.filter.cycleForward | ctrl+o | Cycle tree filter forward |
app.tree.filter.cycleBackward | shift+ctrl+o | Cycle tree filter backward |
Scoped Models Selector
Used inside the scoped models selector (opened via /scoped-models).
| Keybinding id | Default | Description |
|---|---|---|
app.models.enableAll | ctrl+a | Enable all models (or all matching the current search) |
app.models.clearAll | ctrl+x | Clear all models (or all matching the current search) |
app.models.toggleProvider | ctrl+p | Toggle all models for the current provider |
app.models.reorderUp | alt+up | Move the selected model up in the cycle order |
app.models.reorderDown | alt+down | Move the selected model down in the cycle order |