# Customize keyboard shortcuts in Claude Code

> Source: <https://code.claude.com/docs/en/keybindings>
> Published: 2026-06-05 09:18:39+00:00

Customizable keyboard shortcuts require Claude Code v2.1.18 or later. Check your version with `claude --version`

.

Claude Code supports customizable keyboard shortcuts. Run `/keybindings`

to create or open your configuration file at `~/.claude/keybindings.json`

.
## Configuration file

The keybindings configuration file is an object with a `bindings`

array. Each block specifies a context and a map of keystrokes to actions.
Changes to the keybindings file are automatically detected and applied without restarting Claude Code.

| Field | Description |
|---|
`$schema` | Optional JSON Schema URL for editor autocompletion |
`$docs` | Optional documentation URL |
`bindings` | Array of binding blocks by context |

This example binds `Ctrl+E`

to open an external editor in the chat context, and unbinds `Ctrl+U`

:
## Contexts

Each binding block specifies a **context** where the bindings apply:
| Context | Description |
|---|
`Global` | Applies everywhere in the app |
`Chat` | Main chat input area |
`Autocomplete` | Autocomplete menu is open |
`Settings` | Settings menu |
`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 navigation in select dialogs |
`Footer` | Footer indicator navigation (tasks, teams, diff) |
`MessageSelector` | Rewind and summarize dialog message selection |
`DiffDialog` | Diff viewer navigation |
`ModelPicker` | Model picker effort level |
`Select` | Generic select/list components |
`Plugin` | Plugin dialog (browse, discover, manage) |
`Scroll` | Conversation scrolling and text selection in fullscreen mode |
`Doctor` | `/doctor` diagnostics screen |

## Available actions

Actions follow a `namespace:action`

format, such as `chat:submit`

to send a message or `app:toggleTodos`

to show the task list. Each context has specific actions available.
### App actions

Actions available in the `Global`

context:
| Action | Default | Description |
|---|
`app:interrupt` | Ctrl+C | Cancel current operation |
`app:exit` | Ctrl+D | Exit Claude Code |
`app:redraw` | (unbound) | Force terminal redraw |
`app:toggleTodos` | Ctrl+T | Toggle task list visibility |
`app:toggleTranscript` | Ctrl+O | Toggle verbose transcript |

### History actions

Actions for navigating command history:
| Action | Default | Description |
|---|
`history:search` | Ctrl+R | Open history search |
`history:previous` | Up | Previous history item |
`history:next` | Down | Next history item |

### Chat actions

Actions available in the `Chat`

context:
| Action | Default | Description |
|---|
`chat:cancel` | Escape | Cancel current input |
`chat:clearInput` | Ctrl+L | Force a full screen redraw, preserving input. In [fullscreen rendering](/docs/en/fullscreen#clear-the-conversation), press twice within two seconds to run `/clear` |
`chat:clearScreen` | Cmd+K | In [fullscreen rendering](/docs/en/fullscreen#clear-the-conversation), press twice within two seconds to run `/clear` |
`chat:killAgents` | Ctrl+X Ctrl+K | Kill all running [background subagents](/docs/en/sub-agents#run-subagents-in-foreground-or-background) in this session |
`chat:cycleMode` | Shift+Tab* | Cycle permission modes |
`chat:modelPicker` | Meta+P | Open model picker |
`chat:fastMode` | Meta+O | Toggle fast mode |
`chat:thinkingToggle` | Meta+T | Toggle extended thinking |
`chat:submit` | Enter | Submit message |
`chat:newline` | Ctrl+J | Insert a newline without submitting |
`chat:undo` | Ctrl+_, Ctrl+Shift+- | Undo last action |
`chat:externalEditor` | Ctrl+G, Ctrl+X Ctrl+E | Open in external editor |
`chat:stash` | Ctrl+S | Stash current prompt |
`chat:imagePaste` | Ctrl+V (Alt+V on Windows and WSL) | Paste image from clipboard. On WSL, both shortcuts are bound by default |

*On Windows without VT mode (Node <24.2.0/<22.17.0, Bun <1.2.23), defaults to Meta+M.
### Autocomplete actions

Actions available in the `Autocomplete`

context:
| Action | Default | Description |
|---|
`autocomplete:accept` | Tab | Accept suggestion |
`autocomplete:dismiss` | Escape | Dismiss menu |
`autocomplete:previous` | Up | Previous suggestion |
`autocomplete:next` | Down | Next suggestion |

### Confirmation actions

Actions available in the `Confirmation`

context:
| Action | Default | Description |
|---|
`confirm:yes` | Y, Enter | Confirm action |
`confirm:no` | N, Escape | Decline action |
`confirm:previous` | Up | Previous option |
`confirm:next` | Down | Next option |
`confirm:nextField` | Tab | Next field |
`confirm:previousField` | (unbound) | Previous field |
`confirm:toggle` | Space | Toggle selection |
`confirm:cycleMode` | Shift+Tab | Cycle permission modes |
`confirm:toggleExplanation` | Ctrl+E | Toggle permission explanation |

### Permission actions

Actions available in the `Confirmation`

context for permission dialogs:
| Action | Default | Description |
|---|
`permission:toggleDebug` | (unbound) | Toggle permission debug info. The previous default of Ctrl+D was removed in v2.1.146 because it shadowed `app:exit` |

### Transcript actions

Actions available in the `Transcript`

context:
| Action | Default | Description |
|---|
`transcript:toggleShowAll` | Ctrl+E | Toggle show all content |
`transcript:exit` | q, Ctrl+C, Escape | Exit transcript view |

### History search actions

Actions available in the `HistorySearch`

context:
| Action | Default | Description |
|---|
`historySearch:next` | Ctrl+R | Next match |
`historySearch:accept` | Escape, Tab | Accept selection |
`historySearch:cancel` | Ctrl+C | Cancel search |
`historySearch:execute` | Enter | Execute selected command |
`historySearch:cycleScope` | Ctrl+S | Cycle scope: session, project, everywhere |

### Task actions

Actions available in the `Task`

context:
| Action | Default | Description |
|---|
`task:background` | Ctrl+B | Background current task |

### Theme actions

Actions available in the `ThemePicker`

context:
| Action | Default | Description |
|---|
`theme:toggleSyntaxHighlighting` | Ctrl+T | Toggle syntax highlighting |

### Help actions

Actions available in the `Help`

context:
| Action | Default | Description |
|---|
`help:dismiss` | Escape | Close help menu |

### Tabs actions

Actions available in the `Tabs`

context:
| Action | Default | Description |
|---|
`tabs:next` | Tab, Right | Next tab |
`tabs:previous` | Shift+Tab, Left | Previous tab |

### Attachments actions

Actions available in the `Attachments`

context:
| Action | Default | Description |
|---|
`attachments:next` | Right | Next attachment |
`attachments:previous` | Left | Previous attachment |
`attachments:remove` | Backspace, Delete | Remove selected attachment |
`attachments:exit` | Down, Escape | Exit attachment navigation |

Actions available in the `Footer`

context:
| Action | Default | Description |
|---|
`footer:next` | Right | Next footer item |
`footer:previous` | Left | Previous footer item |
`footer:up` | Up | Navigate up in footer (deselects at top) |
`footer:down` | Down | Navigate down in footer |
`footer:openSelected` | Enter | Open selected footer item |
`footer:clearSelection` | Escape | Clear footer selection |

### Message selector actions

Actions available in the `MessageSelector`

context:
| Action | Default | Description |
|---|
`messageSelector:up` | Up, K, Ctrl+P | Move up in list |
`messageSelector:down` | Down, J, Ctrl+N | Move down in list |
`messageSelector:top` | Ctrl+Up, Shift+Up, Meta+Up, Shift+K | Jump to top |
`messageSelector:bottom` | Ctrl+Down, Shift+Down, Meta+Down, Shift+J | Jump to bottom |
`messageSelector:select` | Enter | Select message |

### Diff actions

Actions available in the `DiffDialog`

context:
| Action | Default | Description |
|---|
`diff:dismiss` | Escape | Close diff viewer |
`diff:previousSource` | Left | Previous diff source |
`diff:nextSource` | Right | Next diff source |
`diff:previousFile` | Up, K | Previous file in the file list; scroll up one line in the detail view |
`diff:nextFile` | Down, J | Next file in the file list; scroll down one line in the detail view |
`diff:viewDetails` | Enter | View diff details |
`diff:back` | (context-specific) | Go back in diff viewer |

The diff detail view also binds pager-style keys to the standard [scroll actions](#scroll-actions). These bindings are part of the `DiffDialog`

context and apply only in the detail view; the `Scroll`

context defaults listed under [Scroll actions](#scroll-actions) are unchanged.
| Action | Default | Description |
|---|
`scroll:pageUp` | PageUp | Scroll up half a viewport |
`scroll:pageDown` | PageDown | Scroll down half a viewport |
`scroll:fullPageUp` | Shift+Space, B | Scroll up a full viewport |
`scroll:fullPageDown` | Space | Scroll down a full viewport |
`scroll:top` | G, Home | Jump to the top |
`scroll:bottom` | Shift+G, End | Jump to the bottom |

### Model picker actions

Actions available in the `ModelPicker`

context:
| Action | Default | Description |
|---|
`modelPicker:decreaseEffort` | Left | Decrease effort level |
`modelPicker:increaseEffort` | Right | Increase effort level |
`modelPicker:thisSessionOnly` | s | Apply highlighted model to this session only |

### Select actions

Actions available in the `Select`

context:
| Action | Default | Description |
|---|
`select:next` | Down, J, Ctrl+N | Next option |
`select:previous` | Up, K, Ctrl+P | Previous option |
`select:accept` | Enter | Accept selection |
`select:cancel` | Escape | Cancel selection |

### Plugin actions

Actions available in the `Plugin`

context:
| Action | Default | Description |
|---|
`plugin:toggle` | Space | Toggle plugin selection |
`plugin:install` | I | Install selected plugins |
`plugin:favorite` | F | Favorite the selected plugin so it sorts near the top of the Installed tab |

### Settings actions

Actions available in the `Settings`

context:
| Action | Default | Description |
|---|
`settings:search` | / | Enter search mode |
`settings:retry` | R | Retry loading usage data (on error) |
`settings:close` | Enter | Save changes and close the config panel. Escape discards changes and closes |

### Doctor actions

Actions available in the `Doctor`

context:
| Action | Default | Description |
|---|
`doctor:fix` | F | Send the diagnostics report to Claude to fix the reported issues. Only active when issues are found |

### Voice actions

Actions available in the `Chat`

context when [voice dictation](/docs/en/voice-dictation) is enabled:
| Action | Default | Description |
|---|
`voice:pushToTalk` | Space | Dictate a prompt. Hold or tap depending on `/voice` mode |

Actions available in the `Scroll`

context when [fullscreen rendering](/docs/en/fullscreen) is enabled:
| Action | Default | Description |
|---|
`scroll:lineUp` | (unbound) | Scroll up one line. Mouse wheel scrolling triggers this action |
`scroll:lineDown` | (unbound) | Scroll down one line. Mouse wheel scrolling triggers this action |
`scroll:pageUp` | PageUp | Scroll up half the viewport height |
`scroll:pageDown` | PageDown | Scroll down half the viewport height |
`scroll:top` | Ctrl+Home | Jump to the start of the conversation |
`scroll:bottom` | Ctrl+End | Jump to the latest message and re-enable auto-follow |
`scroll:halfPageUp` | (unbound) | Scroll up half the viewport height. Same behavior as `scroll:pageUp` , provided for vi-style rebinds |
`scroll:halfPageDown` | (unbound) | Scroll down half the viewport height. Same behavior as `scroll:pageDown` , provided for vi-style rebinds |
`scroll:fullPageUp` | (unbound) | Scroll up the full viewport height |
`scroll:fullPageDown` | (unbound) | Scroll down the full viewport height |
`selection:copy` | Ctrl+Shift+C / Cmd+C | Copy the selected text to the clipboard |
`selection:clear` | (unbound) | Clear the active text selection |
`selection:extendLeft` | Shift+Left | Extend the active selection one column left |
`selection:extendRight` | Shift+Right | Extend the active selection one column right |
`selection:extendUp` | Shift+Up | Extend the active selection one row up. Scrolls the viewport when the selection reaches the top edge |
`selection:extendDown` | Shift+Down | Extend the active selection one row down. Scrolls the viewport when the selection reaches the bottom edge |
`selection:extendLineStart` | Shift+Home | Extend the active selection to the start of the line |
`selection:extendLineEnd` | Shift+End | Extend the active selection to the end of the line |

## Keystroke syntax

### Modifiers

Use modifier keys with the `+`

separator:
`ctrl`

or `control`

- Control key
`shift`

- Shift key
`alt`

, `opt`

, `option`

, or `meta`

- Alt key on Windows and Linux, Option key on macOS
`cmd`

, `command`

, `super`

, or `win`

- Command key on macOS, Windows key on Windows, Super key on Linux

The `cmd`

group is only detected in terminals that report the Super modifier, such as those supporting the Kitty keyboard protocol or xterm’s `modifyOtherKeys`

mode. Most terminals do not send it, so use `ctrl`

or `meta`

for bindings you want to work everywhere.
For example:
### Uppercase letters

A standalone uppercase letter implies Shift. For example, `K`

is equivalent to `shift+k`

. This is useful for vim-style bindings where uppercase and lowercase keys have different meanings.
Uppercase letters with modifiers (e.g., `ctrl+K`

) are treated as stylistic and do **not** imply Shift: `ctrl+K`

is the same as `ctrl+k`

.
### Chords

Chords are sequences of keystrokes separated by spaces:
### Special keys

`escape`

or `esc`

- Escape key
`enter`

or `return`

- Enter key
`tab`

- Tab key
`space`

- Space bar
`up`

, `down`

, `left`

, `right`

- Arrow keys
`backspace`

, `delete`

- Delete keys

## Unbind default shortcuts

Set an action to `null`

to unbind a default shortcut:
This also works for chord bindings. Unbinding every chord that shares a prefix frees that prefix for use as a single-key binding:
If you unbind some but not all chords on a prefix, pressing the prefix still enters chord-wait mode for the remaining bindings.
## Reserved shortcuts

These shortcuts cannot be rebound:
| Shortcut | Reason |
|---|
| Ctrl+C | Hardcoded interrupt/cancel |
| Ctrl+D | Hardcoded exit |
| Ctrl+M | Identical to Enter in terminals (both send CR) |
| Caps Lock | Not delivered to terminal applications |

## Terminal conflicts

Some shortcuts may conflict with terminal multiplexers:
| Shortcut | Conflict |
|---|
| Ctrl+B | tmux prefix (press twice to send) |
| Ctrl+A | GNU screen prefix |
| Ctrl+Z | Unix process suspend (SIGTSTP) |

## Vim mode interaction

When vim mode is enabled via `/config`

→ Editor mode, keybindings and vim mode operate independently:
**Vim mode** handles input at the text input level (cursor movement, modes, motions)
**Keybindings** handle actions at the component level (toggle todos, submit, etc.)
- The Escape key in vim mode switches INSERT to NORMAL mode; it does not trigger
`chat:cancel`

- Most Ctrl+key shortcuts pass through vim mode to the keybinding system
- In vim NORMAL mode,
`?`

shows the help menu (vim behavior)
- In vim NORMAL mode,
`/`

opens history search, the same as Ctrl+R in standard mode

## Validation

Claude Code validates your keybindings and shows warnings for:
- Parse errors (invalid JSON or structure)
- Invalid context names
- Reserved shortcut conflicts
- Terminal multiplexer conflicts
- Duplicate bindings in the same context

Run `/doctor`

to see any keybinding warnings.