SpyBara
Go Premium

keybindings.md 2026-01-27 21:01 UTC to 2026-01-28 15:06 UTC

381 added, 0 removed.

2026
Sat 31 03:42 Fri 30 18:07 Thu 29 21:03 Wed 28 15:06 Tue 27 21:01 Mon 26 21:03 Sun 25 03:34 Sat 24 03:29 Fri 23 21:01 Thu 22 21:03 Wed 21 21:05 Tue 20 21:03 Mon 19 21:01 Fri 16 21:01 Wed 14 06:02 Mon 12 21:02 Sun 11 18:02 Sat 10 21:01 Fri 9 21:01 Thu 8 21:02 Wed 7 21:01 Tue 6 21:01 Sat 3 18:02

Customize keyboard shortcuts

Customize keyboard shortcuts in Claude Code with a keybindings configuration file.

Claude Code supports customizable keyboard shortcuts. Run /keybindings to create or open your configuration file at ~/.claude/keybindings.json.

Configuration file

The keybindings configuration file is an object with a bindings array. Each block specifies a context and a map of keystrokes to actions.

Field Description
$schema Optional JSON Schema URL for editor autocompletion
$docs Optional documentation URL
bindings Array of binding blocks by context

This example binds Ctrl+E to open an external editor in the chat context, and unbinds Ctrl+U:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

Contexts

Each binding block specifies a context where the bindings apply:

Context Description
Global Applies everywhere in the app
Chat Main chat input area
Autocomplete Autocomplete menu is open
Settings Settings menu (escape-only dismiss)
Confirmation Permission and confirmation dialogs
Tabs Tab navigation components
Help Help menu is visible
Transcript Transcript viewer
HistorySearch History search mode (Ctrl+R)
Task Background task is running
ThemePicker Theme picker dialog
Attachments Image/attachment bar navigation
Footer Footer indicator navigation (tasks, teams, diff)
MessageSelector Rewind dialog message selection
DiffDialog Diff viewer navigation
ModelPicker Model picker effort level
Select Generic select/list components
Plugin Plugin dialog (browse, discover, manage)

Available actions

Actions follow a namespace:action format, such as chat:submit to send a message or app:toggleTodos to show the task list. Each context has specific actions available.

App actions

Actions available in the Global context:

Action Default Description
app:interrupt Ctrl+C Cancel current operation
app:exit Ctrl+D Exit Claude Code
app:toggleTodos Ctrl+T Toggle task list visibility
app:toggleTranscript Ctrl+O Toggle verbose transcript

History actions

Actions for navigating command history:

Action Default Description
history:search Ctrl+R Open history search
history:previous Up Previous history item
history:next Down Next history item

Chat actions

Actions available in the Chat context:

Action Default Description
chat:cancel Escape Cancel current input
chat:cycleMode Shift+Tab* Cycle permission modes
chat:modelPicker Cmd+P / Meta+P Open model picker
chat:thinkingToggle Cmd+T / Meta+T Toggle extended thinking
chat:submit Enter Submit message
chat:undo Ctrl+_ Undo last action
chat:externalEditor Ctrl+G Open in external editor
chat:stash Ctrl+S Stash current prompt
chat:imagePaste Ctrl+V (Alt+V on Windows) Paste image

*On Windows without VT mode (Node <24.2.0/<22.17.0, Bun <1.2.23), defaults to Meta+M.

Autocomplete actions

Actions available in the Autocomplete context:

Action Default Description
autocomplete:accept Tab Accept suggestion
autocomplete:dismiss Escape Dismiss menu
autocomplete:previous Up Previous suggestion
autocomplete:next Down Next suggestion

Confirmation actions

Actions available in the Confirmation context:

Action Default Description
confirm:yes Y, Enter Confirm action
confirm:no N, Escape Decline action
confirm:previous Up Previous option
confirm:next Down Next option
confirm:nextField Tab Next field
confirm:previousField (unbound) Previous field
confirm:cycleMode Shift+Tab Cycle permission modes
confirm:toggleExplanation Ctrl+E Toggle permission explanation

Permission actions

Actions available in the Confirmation context for permission dialogs:

Action Default Description
permission:toggleDebug Ctrl+D Toggle permission debug info

Transcript actions

Actions available in the Transcript context:

Action Default Description
transcript:toggleShowAll Ctrl+E Toggle show all content
transcript:exit Ctrl+C, Escape Exit transcript view

History search actions

Actions available in the HistorySearch context:

Action Default Description
historySearch:next Ctrl+R Next match
historySearch:accept Escape, Tab Accept selection
historySearch:cancel Ctrl+C Cancel search
historySearch:execute Enter Execute selected command

Task actions

Actions available in the Task context:

Action Default Description
task:background Ctrl+B Background current task

Theme actions

Actions available in the ThemePicker context:

Action Default Description
theme:toggleSyntaxHighlighting Ctrl+T Toggle syntax highlighting

Help actions

Actions available in the Help context:

Action Default Description
help:dismiss Escape Close help menu

Tabs actions

Actions available in the Tabs context:

Action Default Description
tabs:next Tab, Right Next tab
tabs:previous Shift+Tab, Left Previous tab

Attachments actions

Actions available in the Attachments context:

Action Default Description
attachments:next Right Next attachment
attachments:previous Left Previous attachment
attachments:remove Backspace, Delete Remove selected attachment
attachments:exit Down, Escape Exit attachment bar

Actions available in the Footer context:

Action Default Description
footer:next Right Next footer item
footer:previous Left Previous footer item
footer:openSelected Enter Open selected footer item
footer:clearSelection Escape Clear footer selection

Message selector actions

Actions available in the MessageSelector context:

Action Default Description
messageSelector:up Up, K Move up in list
messageSelector:down Down, J Move down in list
messageSelector:top Ctrl+Up, Shift+Up, Meta+Up, Shift+K Jump to top
messageSelector:bottom Ctrl+Down, Shift+Down, Meta+Down, Shift+J Jump to bottom
messageSelector:select Enter Select message

Diff actions

Actions available in the DiffDialog context:

Action Default Description
diff:dismiss Escape Close diff viewer
diff:previousSource Left Previous diff source
diff:nextSource Right Next diff source
diff:previousFile Up Previous file in diff
diff:nextFile Down Next file in diff
diff:viewDetails Enter View diff details
diff:back (context-specific) Go back in diff viewer

Model picker actions

Actions available in the ModelPicker context:

Action Default Description
modelPicker:decreaseEffort Left Decrease effort level
modelPicker:increaseEffort Right Increase effort level

Select actions

Actions available in the Select context:

Action Default Description
select:next Down, J, Ctrl+N Next option
select:previous Up, K, Ctrl+P Previous option
select:accept Enter Accept selection
select:cancel Escape Cancel selection

Plugin actions

Actions available in the Plugin context:

Action Default Description
plugin:toggle Space Toggle plugin selection
plugin:install I Install selected plugins

Settings actions

Actions available in the Settings context:

Action Default Description
settings:search / Enter search mode
settings:retry R Retry loading usage data (on error)

Keystroke syntax

Modifiers

Use modifier keys with the + separator:

  • ctrl or control - Control key
  • alt, opt, or option - Alt/Option key
  • shift - Shift key
  • meta, cmd, or command - Meta/Command key

For example:

ctrl+k          Single key with modifier
shift+tab       Shift + Tab
meta+p          Command/Meta + P
ctrl+shift+c    Multiple modifiers

Uppercase letters

A standalone uppercase letter implies Shift. For example, K is equivalent to shift+k. This is useful for vim-style bindings where uppercase and lowercase keys have different meanings.

Uppercase letters with modifiers (e.g., ctrl+K) are treated as stylistic and do not imply Shift — ctrl+K is the same as ctrl+k.

Chords

Chords are sequences of keystrokes separated by spaces:

ctrl+k ctrl+s   Press Ctrl+K, release, then Ctrl+S

Special keys

  • escape or esc - Escape key
  • enter or return - Enter key
  • tab - Tab key
  • space - Space bar
  • up, down, left, right - Arrow keys
  • backspace, delete - Delete keys

Unbind default shortcuts

Set an action to null to unbind a default shortcut:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null
      }
    }
  ]
}

Reserved shortcuts

These shortcuts cannot be rebound:

Shortcut Reason
Ctrl+C Hardcoded interrupt/cancel
Ctrl+D Hardcoded exit

Terminal conflicts

Some shortcuts may conflict with terminal multiplexers:

Shortcut Conflict
Ctrl+B tmux prefix (press twice to send)
Ctrl+A GNU screen prefix
Ctrl+Z Unix process suspend (SIGTSTP)

Vim mode interaction

When vim mode is enabled (/vim), keybindings and vim mode operate independently:

  • Vim mode handles input at the text input level (cursor movement, modes, motions)
  • Keybindings handle actions at the component level (toggle todos, submit, etc.)
  • The Escape key in vim mode switches INSERT to NORMAL mode; it does not trigger chat:cancel
  • Most Ctrl+key shortcuts pass through vim mode to the keybinding system
  • In vim NORMAL mode, ? shows the help menu (vim behavior)

Validation

Claude Code validates your keybindings and shows warnings for:

  • Parse errors (invalid JSON or structure)
  • Invalid context names
  • Reserved shortcut conflicts
  • Terminal multiplexer conflicts
  • Duplicate bindings in the same context

Run /doctor to see any keybinding warnings.