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