Keybindings

Every keyboard shortcut in Claude Code is an action bound to a keystroke inside a context. You can change any of them, apart from a handful of reserved keys, by editing ~/.claude/keybindings.json. Run /keybindings to create the file (or open it if it exists). Changes are picked up live; there is no need to restart.

If a key is not reaching Claude Code at all (Shift+Enter submitting, Option doing nothing on a Mac), that is a terminal problem rather than a binding problem. See terminal configuration first.

File format

The file is a JSON object with a bindings array. Each entry names a context and maps keystrokes to action names. Two optional keys help your editor: $schema enables autocompletion and validation, and $docs is just a reference URL.

Here is the file I actually use. It sends on Ctrl+Enter only (so a stray Enter adds a line), puts the external editor on Ctrl+E, frees Ctrl+S, and adds y/n to dialogs:

{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "enter": "chat:newline",
        "ctrl+enter": "chat:submit",
        "ctrl+e": "chat:externalEditor",
        "ctrl+s": null
      }
    },
    {
      "context": "Confirmation",
      "bindings": {
        "y": "confirm:yes",
        "n": "confirm:no"
      }
    }
  ]
}

Note: ctrl+enter only arrives as a distinct key in terminals that report extended keys. In others it looks like plain Enter, so test before you commit to a layout like this.

Setting an action to null removes the default binding for that key.

Contexts

A context says when a block of bindings is live.

Versions before v2.1.205 also had a Doctor context with a doctor:fix action for /doctor.

Actions by context

Action names follow namespace:action. "Unbound" means there is no default key, so the action does nothing until you assign one.

Global

History

Chat

On Windows without VT mode (Node older than 24.2.0 or 22.17.0, Bun older than 1.2.23), Shift+Tab defaults become Meta+M, for both chat:cycleMode and confirm:cycleMode.

Voice (Chat context)

Autocomplete

Confirmation and permissions

Every dialog uses confirm:yes and confirm:no for accept and cancel, even if it is not a yes/no question. So if you bind bare y and n here, they act on all dialogs, including ones that never mention those letters. Dialogs that display y/n as options read the letters themselves anyway.

Up to v2.1.280, y and n were bound by default. If /keybindings created your file before then, those two lines are in it and remain active until you delete them. confirm:toggleExplanation (Ctrl+E, a model-written explanation on Bash and PowerShell prompts) existed before v2.1.257.

In most dialogs, a double Ctrl+C or Ctrl+D closes the dialog rather than quitting; the hint after the first press tells you which.

Transcript

History search

The first four apply to the classic renderer's inline search, which always covers every project. historySearch:cycleScope only matters in fullscreen, where Ctrl+R opens a dialog instead; that dialog's Enter/Tab (place match) and Esc (cancel) are fixed.

Task, theme, help

Tabs

These work while the tab row has focus; in some dialogs (/help, /sandbox) they also work from inside the content. Up and Down move focus between the tab row and the content, and lists only respond while focused.

Attachments

Footer

With a footer item selected, Enter opens it even if you remapped Enter in Chat. Chat keys the footer does not use, such as Shift+Tab, keep working.

Select

List panels (/skills, /mcp, /tasks) honour your bindings for all four paging actions. Most other lists, /model included, honour select:first and select:last but always page with PageUp and PageDown. (Before v2.1.280 those lists ignored Home/End; before v2.1.283 /mcp's tool list used fixed paging keys.)

Message selector (rewind)

The rewind list uses Select actions and your Select bindings. MessageSelector has no actions of its own; use it to override a Select action for this list only:

{
  "bindings": [
    { "context": "MessageSelector", "bindings": { "space": "select:accept" } }
  ]
}

Before v2.1.283 the list had messageSelector:up, :down, :top, :bottom and :select. Old bindings to those names still work, mapped to the matching Select action. Home and End jump to the ends (formerly Shift+K and Shift+J).

Model picker and effort slider

The slider's Enter and Escape cannot be rebound. See model configuration for effort levels.

Plugin

Settings

The settings panel reuses two actions. Changes save immediately, so Escape closes without discarding anything.

Agents (agent view)

Requires v2.1.257 or later.

In agent view an Agents binding wins over any Chat or Global binding on the same key, so Ctrl+S groups rather than stashing. Bindings there fire on single keystrokes, so chords (like Ctrl+X Ctrl+E) do not work; the dispatch input's external editor follows chat:externalEditor's single-key binding, Ctrl+G by default.

Scroll and selection (fullscreen)

MacBook users: Ctrl+End cannot be typed, so give scroll:bottom something reachable. A vi-flavoured example:

{
  "bindings": [
    {
      "context": "Scroll",
      "bindings": {
        "ctrl+u": "scroll:halfPageUp",
        "ctrl+f": "scroll:halfPageDown",
        "meta+g": "scroll:bottom"
      }
    }
  ]
}

Ctrl+D would be the natural vi partner for Ctrl+U, but it is reserved for exit, hence Ctrl+F here.

Diff viewer (older dialog)

These reach only the older diff viewer, which /diff opens outside fullscreen after you disable the built-in cc-plugin-diff mod in /plugin. With the mod enabled, /diff shows the newer dialog. Files naming these actions load fine either way.

The file list also honours Select actions (select:previous, select:next, and Enter via select:accept). Bind them in a DiffDialog block to change them for this list only. diff:viewDetails from before v2.1.283 still works as select:accept.

The detail view adds pager keys within DiffDialog: scroll:pageUp (PageUp), scroll:pageDown (PageDown), scroll:fullPageUp (Shift+Space, B), scroll:fullPageDown (Space), scroll:top (G, Home), scroll:bottom (Shift+G, End). The Scroll context defaults are unaffected.

Diff panel (fullscreen)

app:cycleDiffBase lives in DiffPanel; the rest are Global. The built-in cc-plugin-diff mod draws this panel and handles the first three below; the toggle actions only reach the older panel shown when that mod is disabled.

Band above the prompt

The band is where mods draw buttons, inputs and selects. abovePrompt:toggle and abovePrompt:focus apply in Chat; the others apply in whichever context has focus.

Extra defaults: in AbovePrompt, Right/Left also mean next/previous and Space means press; in AbovePromptInput, Down/Up mean next/previous. AbovePrompt also binds Up, Down, PageUp, PageDown, Home and End to the pane scroll actions below, so rebind those in an AbovePrompt block to change them for the band.

Panes

Pane also maps Tab, Shift+Tab, Enter and Escape to the band actions, and pane fields use AbovePromptInput and AbovePromptSelect. See mod interface for what a mod receives.

Keystroke syntax

Modifiers

Join with +:

The cmd family is only seen in terminals that report Super (kitty keyboard protocol, or xterm modifyOtherKeys). Most do not, so prefer ctrl or meta for anything you want portable. Examples: ctrl+g, shift+tab, meta+o, ctrl+shift+x.

Case

Key names are case-insensitive: ctrl+G equals ctrl+g. For Shift plus a letter, write shift+g.

Non-US layouts

Always write Ctrl shortcuts with Latin letters.

• Non-Latin layouts (e.g. Cyrillic): if the terminal uses the kitty keyboard protocol and reports physical key positions, Ctrl shortcuts match by US-layout position, so Ctrl plus the physical W key fires ctrl+w. Otherwise Claude Code matches what the terminal sends: an ASCII control code fires the Latin shortcut, but a Cyrillic character matches nothing.
• Rearranged Latin layouts (e.g. AZERTY): the letter the key types is what matches, so Ctrl and the key labelled A fires ctrl+a.

Chords

Separate keystrokes with spaces, for example ctrl+x ctrl+e. Each press must follow within 3 seconds or the chord is cancelled with a short notice.

Special key names

escape/esc, enter/return, tab, space, up, down, left, right, pageup, pagedown, home, end, backspace, delete, and the mouse wheel events wheelup and wheeldown.

Unbinding and chord prefixes

null removes a binding, chords included. A prefix such as ctrl+x stays reserved (pressing it waits for the second key) while any chord in any active context starts with it. To reclaim the prefix for a single key, unbind every chord that uses it, in the context that defines it.

Default ctrl+x chords:

For example, to make ctrl+x itself open the external editor:

{
  "bindings": [
    { "context": "Task", "bindings": { "ctrl+x ctrl+b": null } },
    { "context": "DiffPanel", "bindings": { "ctrl+x b": null } },
    {
      "context": "Pane",
      "bindings": {
        "ctrl+x left": null, "ctrl+x right": null,
        "ctrl+x up": null, "ctrl+x down": null, "ctrl+x x": null
      }
    },
    { "context": "PaneField", "bindings": { "ctrl+x x": null } },
    {
      "context": "Chat",
      "bindings": {
        "ctrl+x ctrl+k": null, "ctrl+x ctrl+e": null, "ctrl+x enter": null,
        "ctrl+x ctrl+a": null, "ctrl+x ctrl+s": null, "ctrl+x tab": null,
        "ctrl+x": "chat:externalEditor"
      }
    }
  ]
}

Leave even one chord in place and the prefix keeps waiting for a second key. Bear in mind you lose the default way to kill agents, send now, toggle the band and so on, so rebind whichever of those you use.

Reserved keys

Clashes with multiplexers and the shell

Bare keys and text fields

If you bind a plain letter, digit or Space, you can still type it in dialog text fields, such as the Other answer to a question. While such a field is focused, unmodified printable keys go to the field and skip binding lookup. Keys that still run bindings there:

• non-printing keys: Enter, Escape, Tab, arrows
• anything with Ctrl, Alt or Cmd
• the second half of a chord already in progress

At the main prompt it works the other way round: every key is checked against active contexts first, and typed only if nothing claims it.

Vim mode

With Vim editing on (/config → Editor mode), the two systems work at different layers:

• Vim handles text-level input: motions, modes, operators.
• Keybindings handle component-level actions: submit, toggle to-dos and so on.
• Escape switches INSERT to NORMAL and does not fire chat:cancel.
• Most Ctrl shortcuts pass through to keybindings.
• Vim keys cannot be remapped here; for an INSERT-mode pair such as jk to Escape use vimInsertModeRemaps (see interactive mode).
• In NORMAL mode, ? opens help and / opens history search.

Validation

Problems are written to the debug log as warnings. Start with claude --debug to see them. What gets flagged:

• invalid JSON or wrong structure
• misspelt modifiers like crtl+k (the unknown part is dropped, so the binding lands on plain k, which is rarely what you want)
• unknown context names
• action values that are neither a string nor null
• unknown action names (the binding is skipped and the default for that key stays)
• attempts to bind reserved keys
• the same key bound twice in one context

Related

• Terminal configuration
• Interactive mode
• Fullscreen rendering
• Voice dictation
• Commands