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

Issue	Cause	Fix
keybindings.json must have a "bindings" array	Missing wrapper object	Wrap bindings in { "bindings": [...] }
"bindings" must be an array	bindings is not an array	Set "bindings" to an array: [{ context: ..., bindings: ... }]
Unknown context "X"	Typo or invalid context name	Use exact context names from the Available Contexts table
Duplicate key "X" in Y bindings	Same key defined twice in one context	Remove the duplicate; JSON uses only the last value
"X" may not work: ...	Key conflicts with terminal/OS reserved shortcut	Choose a different key (see Reserved Shortcuts section)
Invalid action for "X"	Action value is not a string or null	Actions must be strings like "app:help" or null to unbind

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

Context	Description
Global	Active everywhere, regardless of focus
Chat	When the chat input is focused
Autocomplete	When autocomplete menu is visible
Confirmation	When a confirmation/permission dialog is shown
Help	When the help overlay is open
Transcript	When viewing the transcript
HistorySearch	When searching command history (ctrl+r)
Task	When a task/agent is running in the foreground
ThemePicker	When the theme picker is open
Settings	When the settings menu is open
Tabs	When tab navigation is active
Attachments	When navigating image attachments in a select dialog
Footer	When footer indicators are focused
AbovePrompt	When a plugin's panel above the prompt, or a button in it, has keyboard focus
AbovePromptInput	When a plugin's input field above the prompt has keyboard focus
AbovePromptSelect	When a plugin's select above the prompt has keyboard focus
Pane	When a plugin's pane has keyboard focus
PaneField	When an input field or select in a plugin's pane has keyboard focus
MessageSelector	When the message selector (rewind) is open
DiffDialog	When the diff dialog is open
DiffPanel	When the diff sidebar panel is open
ModelPicker	When the model picker is open
EffortSlider	When the effort slider is open
Select

Available Actions

Action	Default Key(s)	Context
app:interrupt	ctrl+c	Global
app:exit	ctrl+d	Global
app:toggleTodos	ctrl+t	Global
app:toggleTranscript	ctrl+o	Global
app:toggleBrief	ctrl+shift+b	Global
app:toggleReplTab	(none)	Global
app:toggleDiffNoiseFilter	(none)	Global
app:diffFileListUp	meta+up	Global
app:diffFileListDown	meta+down	Global
app:toggleDiffPreSession	(none)	Global
app:cycleDiffBase	ctrl+x b	DiffPanel
app:toggleTerminal	(none)	Global
app:redraw	(none)	Global
app:openArtifact	ctrl+]	Global
history:search	ctrl+r	Global
history:previous	up	Chat
history:next	down	Chat
chat:cancel	escape	Chat
chat:killAgents	ctrl+x ctrl+k	Chat
chat:cycleMode	shift+tab	Chat
chat:modelPicker	meta+p	Chat