skip to content

A Claude Code `~/.claude/keybindings.json` maps `ctl+e` to `chat:externalEditor` and sets `ctrl+c` to null in the Chat context: what actually happens?

level: seniorimportance: nice to knowfreq 7%

answer

  1. a typo is not rejected
  2. unrecognised modifier is dropped
  3. a bare letter gets bound
  4. some keys are reserved
  5. warnings only under --debug

basics

~20 s

The misspelled ctl is dropped, so plain e is bound and typing e at the prompt opens the editor; ctrl+c is reserved and cannot be unbound, so it keeps interrupting. Both problems appear only as debug-log warnings.

solid answer

~30 s

`~/.claude/keybindings.json`, opened with `/keybindings` and hot-reloaded, holds a `bindings` array of blocks, each a `context` plus a map of keystrokes to `namespace:action` names, with `null` to unbind. `ctl+e` is a misspelled modifier: Claude Code drops the unrecognised part and binds plain `e`, and because the main prompt matches keys against bindings before typing them, pressing `e` opens the external editor. `ctrl+c` is reserved, a hardcoded interrupt, so the `null` is ignored with a warning. Validation never blocks startup; it writes warnings to the debug log, visible with `--debug`. The fix is `ctrl+e` and deleting the `ctrl+c` line.

code

json · 12 lines
json
{
  "$schema": "https://www.schemastore.org/claude-code-keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+s": null
      }
    }
  ]
}

go deeper

for a junior

Recall that /keybindings opens ~/.claude/keybindings.json, where you bind keys to actions per context and use null to remove a default.

for a middle

Explain the file's shape: context blocks, namespace:action names, chords within 3 seconds, and the reserved keys that cannot be rebound.

for a senior

Diagnose silent failures: a misspelled modifier binds a bare key, reserved keys are ignored, unknown actions are skipped, and only --debug shows the warnings.

for a principal

Decide whether a team standardises shortcuts at all, given the file is per-user and terminals differ, and weigh portable ctrl and meta bindings against personal preference.

## The file Claude Code reads custom keyboard shortcuts from **`~/.claude/keybindings.json`**. Running `/keybindings` creates the file (with a `$schema` reference for editor autocompletion) or opens it. It is a **global, per-user** file: there is no project-level copy for a repository to ship. Changes are **detected and applied without restarting** Claude Code. The structure is an object with a `bindings` array. Each entry names a **context** and maps **keystrokes** to **actions**: - **Contexts** say where a binding applies: `Global`, `Chat` (the main input), `Autocomplete`, `Confirmation`, `HistorySearch`, `Task` (a task running in the foreground), `Transcript` and others. - **Actions** use a `namespace:action` form: `chat:submit`, `chat:newline`, `chat:externalEditor`, `history:search`, `task:background`, `app:toggleTranscript`. - **`null`** unbinds a default, for example `"ctrl+s": null` frees the stash key. - **Chords** are space-separated keystrokes, such as `ctrl+k ctrl+s`, each pressed within 3 seconds of the previous one. - **Modifiers** are `ctrl`/`control`, `shift`, `alt`/`opt`/`option`/`meta`, and `cmd`/`command`/`super`/`win`. The `cmd` group is only seen in terminals that report the Super modifier, so `ctrl` or `meta` is the portable choice. ## What the broken file actually does Take a `Chat` block containing `"ctl+e": "chat:externalEditor"` and `"ctrl+c": null`. 1. **`ctl+e`** is a misspelled modifier. Claude Code **drops the part it does not recognise and applies the binding to what remains**: plain `e`. At the main prompt every key is matched against the active contexts first and typed only when no binding takes it, so typing the letter `e` now opens the external editor. Since v2.1.283 a warning with a suggested fix is written to the debug log. 2. **`ctrl+c`** is a **reserved shortcut**, hardcoded as interrupt and cancel. It cannot be rebound or unbound; the entry produces a reserved-conflict warning and `Ctrl+C` keeps working as before. ## Reserved and non-remappable keys | Key or group | Why it cannot be bound | | :- | :- | | `Ctrl+C`, `Ctrl+D` | Hardcoded interrupt and exit | | `Ctrl+M`, `Ctrl+[`, `Ctrl+I` | Always received as Enter, Escape and Tab | | `Ctrl+H` | Sends the ASCII backspace byte | | Caps Lock | Never delivered to terminal applications | | Readline word-editing keys (`Alt+B`, `Ctrl+W`, ...) | The file has no actions for them | | Vim-mode keys | Handled by vim mode; only `vimInsertModeRemaps` maps an INSERT sequence to Escape | ## Validation is quiet by design Claude Code validates the file and writes **warnings to the debug log**, visible when started with `--debug`, for parse errors, misspelled modifiers, invalid context names, invalid action values, unknown action names, reserved-shortcut conflicts and duplicate bindings in one context. An unknown action name is **skipped** and the default binding for that key stays in effect. The session does not refuse to start, which is exactly why a bad binding can go unnoticed. ## Things that catch upgraders - Files generated by `/keybindings` before v2.1.280 still list `y` and `n` bound to `confirm:yes` and `confirm:no`; those stay in effect until you delete the lines. - Binding a bare letter in `Confirmation` makes that letter act on dialogs that never show it as a key. - Chords on the `ctrl+x` prefix (`ctrl+x ctrl+e`, `ctrl+x ctrl+s` and others) keep the prefix reserved in their context until every one is unbound. - `Shift+Tab` is the `chat:cycleMode` action; what it cycles between is a separate subject. ## A working version The fixed block binds `ctrl+e` correctly and drops the `ctrl+c` line; a `null` on a non-reserved key such as `ctrl+s` is the legitimate way to unbind.

  • A binding names an action that does not exist. Does the key go dead?
    No. Claude Code skips a binding with an unknown action name and keeps the default binding for that key in effect, logging a warning that `--debug` shows. Before v2.1.246 such a binding could leave the key doing nothing, which is why the warning is worth checking after an upgrade renames an action.
  • Can a repository commit a keybindings file so the whole team gets the same shortcuts?
    No. `keybindings.json` is global only, read from `~/.claude/`. Sharing a layout means distributing the file to each user's home directory; a project checkout cannot change a user's keystrokes this way.

  • Setting ctrl+c to null stops Ctrl+C from interrupting Claude.
  • A misspelled modifier makes Claude Code reject the whole keybindings file.
  • Keybinding changes only take effect after restarting Claude Code.
  • A repository can ship its own keybindings.json for the team.
  • Vim-mode motions can be remapped in keybindings.json.

Assumes Claude Code 2.1.286; the debug-log warning for a misspelled modifier arrived in 2.1.283, and default y/n confirmation bindings were removed in 2.1.280.