Claude Code Keybindings

Your fingers expect Ctrl+K to pop a command palette. Claude Code has other ideas. Each wrong reflex costs a second of thought and a beat of flow.

The cost stacks up. A long Claude Code session runs on muscle memory, and bad defaults fight that muscle memory on every keystroke. Years of VS Code, Vim, or Emacs habits don't unlearn on command. Retraining your hands to match someone else's shortcut layout is wasted effort.

The fix is built in. One JSON file, organized by context, handles every shortcut you care about. You get chord sequences, modifier stacks, and the option to kill a default outright. Edits go live the moment you save. Here is how to wire it up so the tool feels like yours.

First Steps With Custom Keybindings

Type /keybindings inside Claude Code. That slash command creates or opens ~/.claude/keybindings.json for you. The file lives in the usual ~/.claude/ folder next to the rest of your settings.

The shape of the file is plain:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "$docs": "https://code.claude.com/docs/en/keybindings",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+e": "chat:externalEditor",
        "ctrl+u": null
      }
    }
  ]
}

Three top-level keys do all the work:

• $schema - Optional. Pointing at the JSON Schema URL hands your editor free autocompletion and validation. Worth keeping.
• $docs - Optional. A docs link for quick lookups.
• bindings - The array where your shortcuts live. One entry per context.

That schema field is a quiet win. Any editor with JSON Schema support then suggests valid actions and context names as you type.

Saved files are picked up on the fly. Edit, hit save, and the new bindings work right away. No restart.

How Contexts Work

Each binding sits inside a context, and the context decides when the shortcut is live. A Chat binding only fires when the main chat input has focus. Reuse the same keys across contexts and they can each do something different.

There are 17 contexts in Claude Code:

Global is the odd one. A shortcut here fires no matter what view you are in. Use it with care. A global Ctrl+K will trigger inside chat, inside autocomplete, and inside a diff review.

Every Action, Listed

Action names follow a namespace:action pattern. Below is every action in every context, with its default key.

Global Actions

These fire anywhere:

Heavy users of the task list hit app:toggleTodos all day. If Ctrl+T clashes with your terminal, move it somewhere friendlier.

Chat Actions

Where most of your keystrokes land:

On Windows without VT mode, chat:cycleMode falls back to Meta+M. That applies to Node builds older than 24.2.0/22.17.0, and Bun older than 1.2.23. The shortcut controls permission modes, which gates what Claude is allowed to do.

History Actions

Walking back through past prompts:

Autocomplete Actions

Active while the suggestions menu is open:

Confirmation Actions

Bindings for permission and approval dialogs:

Transcript Actions

History Search Actions

Task Actions

Theme, Help, and Settings Actions

Navigation Actions

Tabs, attachments, footer, diffs, model picker, selects, and the message selector all live here:

Keystroke Syntax

The syntax for defining key combinations is easy on the eyes.

Modifiers

Join modifier keys to the target key with +:

• ctrl or control for the Control key
• alt, opt, or option for Alt/Option
• shift for Shift
• meta, cmd, or command for Meta/Command

A few examples:

ctrl+k          Single modifier + key
shift+tab       Shift + Tab
meta+p          Command/Meta + P
ctrl+shift+c    Multiple modifiers

Uppercase Letters and Shift

A bare uppercase letter already means Shift. So K in a binding is the same thing as shift+k. Handy for Vim-style layouts where j and J (or k and K) map to different actions.

One gotcha. Once a modifier is attached, case stops mattering. ctrl+K and ctrl+k are the same binding. With modifiers present, uppercase is only cosmetic.

Chord Sequences

Chords give you multi-key shortcuts. Put a space between the keystrokes:

ctrl+k ctrl+s Press Ctrl+K, release, then press Ctrl+S

That opens up far more room than single-key bindings. Running low on unused key combos? Chords add hundreds of fresh options without stepping on anything.

Special Keys

Non-character keys have their own names:

• escape or esc
• enter or return
• tab
• space
• up, down, left, right
• backspace, delete

Turning Off Default Shortcuts

Set the action to null and the default goes away:

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

Handy when a default steps on your terminal, your OS, or another tool running next to Claude Code. You can also null out a default and then give that same key a new action.

Reserved Shortcuts

Two keys are hardcoded. They cannot be rebound:

Claude Code will reject any attempt to remap these, and that is the right call. Every terminal user alive expects Ctrl+C to interrupt and Ctrl+D to exit. Those are Unix conventions.

Terminal Multiplexer Conflicts

Running Claude Code inside tmux, GNU screen, or a similar multiplexer? The prefix keys will bite you:

task:background ships with Ctrl+B, which is exactly the tmux prefix. If you live in tmux, remap it on day one:

{
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+b": null,
        "ctrl+shift+b": "task:background"
      }
    }
  ]
}

That conflict trips up a lot of developers who run Claude Code inside multiplexed sessions.

Vim Mode Interaction

Turn on vim mode with /vim and it works on a separate layer from keybindings:

• Vim mode handles text editing. Cursor motion, INSERT and NORMAL modes, motions, text objects.
• Keybindings handle app-level actions. Toggling the task list, submitting a message, opening the model picker.

The Escape key is the clearest split. Inside vim mode, Escape leaves INSERT and drops to NORMAL. It does not call chat:cancel. Most Ctrl+key shortcuts cut straight through vim mode into the keybinding layer, so Ctrl+T still toggles the task list even from NORMAL mode.

In NORMAL mode, ? pulls up the vim-style help, not Claude Code's help screen.

Heavy thinking-mode users on vim mode should park chat:thinkingToggle behind a chord that stays clear of vim motions. The interactive mode guide covers how vim mode, slash commands, and the rest of the interactive features slot together.

Validation and Diagnostics

Claude Code checks your keybindings file on every save and flags:

• Parse errors in JSON syntax or structure
• Invalid context names that don't match the 17 supported contexts
• Reserved shortcut conflicts if you try to rebind Ctrl+C or Ctrl+D
• Terminal multiplexer conflicts for Ctrl+B, Ctrl+A, and Ctrl+Z
• Duplicate bindings in the same context

Hit /doctor to see every keybinding warning in one place. That is the fastest path to figuring out why a shortcut misbehaves.

Practical Configuration Examples

A few configurations pulled from real-world setups.

VS Code User Configuration

Coming from VS Code and want the usual shortcuts back:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+k ctrl+s": "chat:stash",
        "ctrl+shift+p": "chat:modelPicker",
        "ctrl+g": "chat:externalEditor"
      }
    },
    {
      "context": "Global",
      "bindings": {
        "ctrl+shift+t": "app:toggleTodos"
      }
    }
  ]
}

tmux-Friendly Setup

Sidesteps the tmux prefix clash:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Task",
      "bindings": {
        "ctrl+b": null,
        "ctrl+shift+b": "task:background"
      }
    }
  ]
}

Minimal Distraction Setup

Kill the shortcuts your fingers keep triggering by accident:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+s": null,
        "ctrl+u": null
      }
    }
  ]
}

Chord-Based Power User

Park rarer features behind chords so the single-key combos stay free:

{
  "$schema": "https://platform.claude.com/docs/schemas/claude-code/keybindings.json",
  "bindings": [
    {
      "context": "Chat",
      "bindings": {
        "ctrl+k ctrl+t": "chat:thinkingToggle",
        "ctrl+k ctrl+m": "chat:modelPicker",
        "ctrl+k ctrl+e": "chat:externalEditor"
      }
    }
  ]
}

Your most-used actions keep their one-key bindings. Everything else is one chord away.

Building Your Own Configuration

Go slow. Remapping the entire app in one pass is a trap. Here is a saner approach:

1. Run /keybindings to generate the config file
2. Pick your three worst pain points (shortcut clashes, missing bindings, accidental fires)
3. Fix those three first with targeted entries
4. Run /doctor to validate the file
5. Spend a full Claude Code session on it and note what still snags
6. Iterate by adding or tweaking bindings as friction shows up

Customizing every possible shortcut is not the goal. The goal is closing the gap between what your hands expect and what Claude Code does. Five to ten bindings is usually enough for the tool to feel native.

Keybindings handle the physical side. CLAUDE.md and custom slash commands handle the behavioral side. Wire them together and Claude Code starts to feel like it was built around your workflow.