Customize keyboard shortcuts

Customizable keyboard shortcuts require Claude Code v2.1.18 or later. Check your version with claude --version.

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
`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 navigation in select dialogs
`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)
`Scroll`	Conversation scrolling and text selection in fullscreen mode
`Doctor`	`/doctor` diagnostics screen

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:redraw`	(unbound)	Force terminal redraw
`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:clearInput`	Ctrl+L	Clear prompt input and force a full screen redraw
`chat:killAgents`	Ctrl+X Ctrl+K	Kill all background agents
`chat:cycleMode`	Shift+Tab*	Cycle permission modes
`chat:modelPicker`	Meta+P	Open model picker
`chat:fastMode`	Meta+O	Toggle fast mode
`chat:thinkingToggle`	Meta+T	Toggle extended thinking
`chat:submit`	Enter	Submit message
`chat:newline`	Ctrl+J	Insert a newline without submitting
`chat:undo`	Ctrl+_, Ctrl+Shift+-	Undo last action
`chat:externalEditor`	Ctrl+G, Ctrl+X Ctrl+E	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:toggle`	Space	Toggle selection
`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`	q, 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 navigation

Actions available in the Footer context:

Action	Default	Description
`footer:next`	Right	Next footer item
`footer:previous`	Left	Previous footer item
`footer:up`	Up	Navigate up in footer (deselects at top)
`footer:down`	Down	Navigate down in footer
`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, Ctrl+P	Move up in list
`messageSelector:down`	Down, J, Ctrl+N	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
`plugin:favorite`	F	Favorite the selected plugin so it sorts near the top of the Installed tab

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)
`settings:close`	Enter	Save changes and close the config panel. Escape discards changes and closes

Doctor actions

Actions available in the Doctor context:

Action	Default	Description
`doctor:fix`	F	Send the diagnostics report to Claude to fix the reported issues. Only active when issues are found

Voice actions

Actions available in the Chat context when voice dictation is enabled:

Action	Default	Description
`voice:pushToTalk`	Space	Dictate a prompt. Hold or tap depending on `/voice` mode

Scroll actions

Actions available in the Scroll context when fullscreen rendering is enabled:

Action	Default	Description
`scroll:lineUp`	(unbound)	Scroll up one line. Mouse wheel scrolling triggers this action
`scroll:lineDown`	(unbound)	Scroll down one line. Mouse wheel scrolling triggers this action
`scroll:pageUp`	PageUp	Scroll up half the viewport height
`scroll:pageDown`	PageDown	Scroll down half the viewport height
`scroll:top`	Ctrl+Home	Jump to the start of the conversation
`scroll:bottom`	Ctrl+End	Jump to the latest message and re-enable auto-follow
`scroll:halfPageUp`	(unbound)	Scroll up half the viewport height. Same behavior as `scroll:pageUp`, provided for vi-style rebinds
`scroll:halfPageDown`	(unbound)	Scroll down half the viewport height. Same behavior as `scroll:pageDown`, provided for vi-style rebinds
`scroll:fullPageUp`	(unbound)	Scroll up the full viewport height
`scroll:fullPageDown`	(unbound)	Scroll down the full viewport height
`selection:copy`	Ctrl+Shift+C / Cmd+C	Copy the selected text to the clipboard
`selection:clear`	(unbound)	Clear the active text selection
`selection:extendLeft`	Shift+Left	Extend the active selection one column left
`selection:extendRight`	Shift+Right	Extend the active selection one column right
`selection:extendUp`	Shift+Up	Extend the active selection one row up. Scrolls the viewport when the selection reaches the top edge
`selection:extendDown`	Shift+Down	Extend the active selection one row down. Scrolls the viewport when the selection reaches the bottom edge
`selection:extendLineStart`	Shift+Home	Extend the active selection to the start of the line
`selection:extendLineEnd`	Shift+End	Extend the active selection to the end of the line

Keystroke syntax

Modifiers

Use modifier keys with the + separator:

ctrl or control - Control key
shift - Shift key
alt, opt, option, or meta - Alt key on Windows and Linux, Option key on macOS
cmd, command, super, or win - Command key on macOS, Windows key on Windows, Super key on Linux

The cmd group is only detected in terminals that report the Super modifier, such as those supporting the Kitty keyboard protocol or xterm’s modifyOtherKeys mode. Most terminals do not send it, so use ctrl or meta for bindings you want to work everywhere. For example:

ctrl+k          Ctrl + K
shift+tab       Shift + Tab
meta+p          Option + P on macOS, Alt + P elsewhere
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
      }
    }
  ]
}

This also works for chord bindings. Unbinding every chord that shares a prefix frees that prefix for use as a single-key binding:

{
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+x ctrl+k": null,
        "ctrl+x ctrl+e": null,
        "ctrl+x": "chat:newline"
      }
    }
  ]
}

If you unbind some but not all chords on a prefix, pressing the prefix still enters chord-wait mode for the remaining bindings.

Reserved shortcuts

These shortcuts cannot be rebound:

Shortcut	Reason
Ctrl+C	Hardcoded interrupt/cancel
Ctrl+D	Hardcoded exit
Ctrl+M	Identical to Enter in terminals (both send CR)

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 via /config → Editor mode, 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.

Settings and permissions

Model and responses

Interface

Configuration file

Contexts

Available actions

App actions

History actions

Chat actions

Autocomplete actions

Confirmation actions

Permission actions

Transcript actions

History search actions

Task actions

Theme actions

Help actions

Tabs actions

Attachments actions

Footer actions

Message selector actions

Diff actions

Model picker actions

Select actions

Plugin actions

Settings actions

Doctor actions

Voice actions

Scroll actions

Keystroke syntax

Modifiers

Uppercase letters

Chords

Special keys

Unbind default shortcuts

Reserved shortcuts

Terminal conflicts

Vim mode interaction

Validation

Settings and permissions

Model and responses

Interface

​Configuration file

​Contexts

​Available actions

​App actions

​History actions

​Chat actions

​Autocomplete actions

​Confirmation actions

​Permission actions

​Transcript actions

​History search actions

​Task actions

​Theme actions

​Help actions

​Tabs actions

​Attachments actions

​Footer actions

​Message selector actions

​Diff actions

​Model picker actions

​Select actions

​Plugin actions

​Settings actions

​Doctor actions

​Voice actions

​Scroll actions

​Keystroke syntax

​Modifiers

​Uppercase letters

​Chords

​Special keys

​Unbind default shortcuts

​Reserved shortcuts

​Terminal conflicts

​Vim mode interaction

​Validation

Configuration file

Contexts

Available actions

App actions

History actions

Chat actions

Autocomplete actions

Confirmation actions

Permission actions

Transcript actions

History search actions

Task actions

Theme actions

Help actions

Tabs actions

Attachments actions

Footer actions

Message selector actions

Diff actions

Model picker actions

Select actions

Plugin actions

Settings actions

Doctor actions

Voice actions

Scroll actions

Keystroke syntax

Modifiers

Uppercase letters

Chords

Special keys

Unbind default shortcuts

Reserved shortcuts

Terminal conflicts

Vim mode interaction

Validation