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.

Changes to the keybindings file are automatically detected and applied without restarting Claude Code.

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://www.schemastore.org/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 and summarize 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

Footer actions

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.