Keybindings Help

Keybindings Skill

Create or modify ~/.claude/keybindings.json to customize keyboard shortcuts.

CRITICAL: Read Before Write

Always read ~/.claude/keybindings.json first (it may not exist yet). Merge changes with existing bindings — never replace the entire file.

• Use Edit tool for modifications to existing files
• Use Write tool only if the file does not exist yet

File Format

{
  "$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"
      }
    }
  ]
}

Always include the $schema and $docs fields.

Keystroke Syntax

Modifiers (combine with +):

• ctrl (alias: control)
• alt (aliases: opt, option) — note: alt and meta are identical in terminals
• shift
• meta (aliases: cmd, command)

Special keys: escape/esc, enter/return, tab, space, backspace, delete, up, down, left, right

Chords: Space-separated keystrokes, e.g. ctrl+k ctrl+s (1-second timeout between keystrokes)

Examples: ctrl+shift+p, alt+enter, ctrl+k ctrl+n

Unbinding Default Shortcuts

Set a key to null to remove its default binding:

{
  "context": "Chat",
  "bindings": {
    "ctrl+s": null
  }
}

How User Bindings Interact with Defaults

• User bindings are additive — they are appended after the default bindings
• To move a binding to a different key: unbind the old key (null) AND add the new binding
• A context only needs to appear in the user's file if they want to change something in that context

Common Patterns

Rebind a key

To change the external editor shortcut from ctrl+g to ctrl+e:

{
  "context": "Chat",
  "bindings": {
    "ctrl+g": null,
    "ctrl+e": "chat:externalEditor"
  }
}

Add a chord binding

{
  "context": "Global",
  "bindings": {
    "ctrl+k ctrl+t": "app:toggleTodos"
  }
}

Behavioral Rules

1. Only include contexts the user wants to change (minimal overrides)
2. Validate that actions and contexts are from the known lists below
3. Warn the user proactively if they choose a key that conflicts with reserved shortcuts or common tools like tmux (ctrl+b) and screen (ctrl+a)
4. When adding a new binding for an existing action, the new binding is additive (existing default still works unless explicitly unbound)
5. To fully replace a default binding, unbind the old key AND add the new one

Validation

Claude Code validates ~/.claude/keybindings.json when it loads; warnings go to the debug log. After editing the file, re-check it against the rules below and fix anything that matches.

Common Issues and Fixes

Example validation warnings (debug log)

[keybindings] Found 2 validation issue(s)
[keybindings] [error] Unknown context "chat" — Valid contexts: Global, Chat, Autocomplete, ...
[keybindings] [warning] "ctrl+c" may not work: Terminal interrupt (SIGINT)

Errors prevent bindings from working and must be fixed. Warnings indicate potential conflicts but the binding may still work.

Reserved Shortcuts

Non-rebindable (errors)

• ctrl+c — Cannot be rebound - used for interrupt/exit (hardcoded)
• ctrl+d — Cannot be rebound - used for exit (hardcoded)
• ctrl+m — Cannot be rebound - identical to Enter in terminals (both send CR)
• ctrl+[ — Cannot be rebound - identical to Escape in terminals
• ctrl+i — Cannot be rebound - identical to Tab in terminals
• ctrl+h — Cannot be rebound - identical to Backspace in terminals
• capslock — Caps Lock is not delivered to terminal applications

Terminal reserved (errors/warnings)

• ctrl+z — Unix process suspend (SIGTSTP) (may conflict)
• ctrl+\ — Terminal quit signal (SIGQUIT) (will not work)

macOS reserved (errors)

• cmd+c — macOS system copy
• cmd+v — macOS system paste
• cmd+x — macOS system cut
• cmd+q — macOS quit application
• cmd+w — macOS close window/tab
• cmd+tab — macOS app switcher
• cmd+space — macOS Spotlight

Available Contexts