Configure Claude Code keybindings.json: 17 contexts, keystroke syntax, chord sequences, modifier combinations, and how to unbind any default shortcut instantly.
Configure custom keyboard shortcuts in Claude Code. Reference for all 17 contexts, keystroke syntax, and keybindings.json examples.
Your muscle memory says Ctrl+K should open a command palette. Claude Code disagrees. Every time you reach for a familiar shortcut and get the wrong action, you lose focus and break your flow.
This friction compounds. Developers who spend hours in Claude Code sessions build unconscious habits around keyboard shortcuts. When the defaults don't match your mental model, you're fighting the tool instead of using it. If you've come from VS Code, Vim, Emacs, or any terminal-heavy workflow, you already have years of shortcut patterns wired into your fingers. Forcing yourself to learn new ones is a waste of cognitive effort.
Claude Code solves this with a fully customizable keybinding system. You define every shortcut in a single JSON file, organized by context, with support for chord sequences, modifier combinations, and the ability to unbind any default. Changes apply instantly without restarting. Here's how to set it up and make Claude Code feel like an extension of your existing workflow.
Run the /keybindings slash command inside Claude Code. This creates (or opens) your configuration file at ~/.claude/keybindings.json. If you're new to configuring Claude Code, this file sits alongside your other settings in the ~/.claude/ directory.
$schema - Optional. Point this at Claude's JSON Schema URL and your editor gives you autocompletion and validation for free. Worth adding.
$docs - Optional. Documentation URL for quick reference.
bindings - The array where all your custom shortcuts live. Each entry targets a specific context.
The $schema field alone makes configuration significantly easier. If you use VS Code or any editor with JSON Schema support, you get inline suggestions for every valid action and context name.
Changes to keybindings.json are detected and applied automatically. No restart needed. Edit, save, and your new shortcuts are live immediately.
Every binding belongs to a context, which tells Claude Code when that shortcut is active. A shortcut bound in the Chat context only fires when you're typing in the main chat input. The same key combination can do different things in different contexts.
Claude Code has 17 contexts:
Context
When It's Active
Global
Everywhere in the app
Chat
Main chat input area
Autocomplete
Autocomplete menu is open
Settings
Settings menu is open
Confirmation
Permission and confirmation dialogs
Tabs
Tab navigation components
Help
Help menu is visible
Transcript
Transcript viewer
HistorySearch
History search mode (Ctrl+R)
Task
Background task is running
ThemePicker
Theme picker dialog
Attachments
Image/attachment bar navigation
Footer
Footer indicator navigation
MessageSelector
Rewind dialog message selection
DiffDialog
Diff viewer navigation
ModelPicker
Model picker effort level
Select
Generic select/list components
Plugin
Plugin dialog (browse, discover, manage)
The Global context is special. Bindings here apply everywhere, regardless of what dialog or view is active. Use it sparingly. If you bind Ctrl+K globally, it fires whether you're in chat, browsing autocomplete suggestions, or reviewing diffs.
If you use task management features, app:toggleTodos is one you'll reach for constantly. Consider binding it to something more accessible if Ctrl+T conflicts with your terminal.
The main input area where you spend most of your time:
Action
Default
What It Does
chat:cancel
Escape
Cancel current input
chat:cycleMode
Shift+Tab
Cycle permission modes
chat:modelPicker
Cmd+P / Meta+P
Open model picker
chat:thinkingToggle
Cmd+T / Meta+T
Toggle extended thinking
chat:submit
Enter
Submit message
chat:undo
Ctrl+_
Undo last action
chat:externalEditor
Ctrl+G
Open in external editor
chat:stash
Ctrl+S
Stash current prompt
chat:imagePaste
Ctrl+V (Alt+V on Windows)
Paste image
Note: chat:cycleMode defaults to Meta+M on Windows without VT mode (Node versions before 24.2.0/22.17.0, or Bun before 1.2.23). This ties directly into permission management for controlling what Claude can and can't do.
A standalone uppercase letter implies Shift. Writing K in your bindings is the same as writing shift+k. This is particularly useful for Vim-style bindings where j and J (or k and K) do different things.
One important detail: uppercase letters with modifiers do NOT imply Shift. So ctrl+K is identical to ctrl+k. The uppercase is treated as purely stylistic when modifiers are present.
Chords let you create multi-key shortcuts. Separate the keystrokes with a space:
ctrl+k ctrl+s Press Ctrl+K, release, then press Ctrl+S
This gives you a much larger namespace for shortcuts. If you're running out of single-key combinations, chords open up hundreds of possibilities without conflicting with existing bindings.
This is useful when a default shortcut conflicts with your terminal, your OS, or a tool you use alongside Claude Code. You can also unbind a default and then rebind the same key to a different action.
Two shortcuts are hardcoded and cannot be rebound:
Shortcut
Reason
Ctrl+C
Hardcoded interrupt/cancel
Ctrl+D
Hardcoded exit
Don't try to rebind these. Claude Code won't accept it, and for good reason. Ctrl+C as interrupt and Ctrl+D as exit are Unix conventions that every terminal user expects.
When vim mode is enabled (toggle with /vim), keybindings and vim mode operate on different layers:
Vim mode controls text input: cursor movement, modes (INSERT, NORMAL), motions, and text objects
Keybindings control application actions: toggling the task list, submitting messages, opening the model picker
The key distinction is the Escape key. In vim mode, Escape switches from INSERT to NORMAL mode. It does not trigger chat:cancel. Most Ctrl+key shortcuts pass through vim mode to the keybinding system, so Ctrl+T still toggles your task list even when you're in NORMAL mode.
In NORMAL mode, pressing ? shows the help menu (standard vim behavior), not the Claude Code help.
If you rely on planning modes heavily and use vim mode, consider binding chat:thinkingToggle to a chord that won't conflict with vim motions. For a full overview of how vim mode, slash commands, and other interactive features fit together, see the interactive mode guide.
Start small. Don't try to remap everything at once. Here's a practical approach:
Run /keybindings to create the config file
Identify your top 3 pain points (conflicting shortcuts, missing shortcuts, accidental triggers)
Fix those first with targeted bindings
Run /doctor to validate
Use Claude Code for a full session and note any remaining friction
Iterate by adding or adjusting bindings as needed
The goal isn't to customize every possible shortcut. It's to eliminate the friction between your muscle memory and Claude Code's behavior. Most developers only need 5-10 custom bindings to feel completely at home. ClaudeFast's Code Kit ships with a pre-tuned settings.json that includes keybinding-friendly defaults alongside its slash commands and hooks, so you start with a solid baseline instead of building from scratch.
If you're building a more comprehensive Claude Code setup, your keybindings work alongside CLAUDE.md configuration and custom slash commands to create a fully personalized environment. The keybindings handle the physical interface. The configuration files handle the behavioral interface. Together, they make Claude Code feel like it was built specifically for your workflow.