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.

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:

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:

History actions

Actions for navigating command history:

Chat actions

Actions available in the Chat context:

*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:

Confirmation actions

Actions available in the Confirmation context:

Permission actions

Actions available in the Confirmation context for permission dialogs:

Transcript actions

Actions available in the Transcript context:

History search actions

Actions available in the HistorySearch context:

Task actions

Actions available in the Task context:

Theme actions

Actions available in the ThemePicker context:

Help actions

Actions available in the Help context:

Tabs actions

Actions available in the Tabs context:

Attachments actions

Actions available in the Attachments context:

Footer actions

Actions available in the Footer context:

Message selector actions

Actions available in the MessageSelector context:

Diff actions

Actions available in the DiffDialog context:

Model picker actions

Actions available in the ModelPicker context:

Select actions

Actions available in the Select context:

Plugin actions

Actions available in the Plugin context:

Settings actions

Actions available in the Settings context:

Doctor actions

Actions available in the Doctor context:

Voice actions

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

Scroll actions

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

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
      }
    }
  ]
}

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:

Terminal conflicts

Some shortcuts may conflict with terminal multiplexers:

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.