name: keybindings-help
description: |-
Use when the user wants to customize keyboard shortcuts, rebind keys, add chord bindings, or modify ~/.claude/keybindings.json. Examples: "rebind ctrl+s", "add a chord shortcut", "change the submit key", "customize keybindings".
user-invocable: false

Keybindings Skill / 键盘快捷键技能

Create or modify ~/.claude/keybindings.json to customize keyboard shortcuts.

创建或修改 ~/.claude/keybindings.json 以自定义键盘快捷键。

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.

始终先读取 ~/.claude/keybindings.json（它可能尚不存在）。将更改与既有绑定合并——绝不整体替换该文件。

• Use Edit tool for modifications to existing files
  修改既有文件时使用 Edit 工具
• Use Write tool only if the file does not exist yet
  仅当文件尚不存在时才使用 Write 工具

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.

始终包含 $schema 和 $docs 字段。

Keystroke Syntax / 按键语法

Modifiers (combine with +):

修饰键（用 + 组合）：

• ctrl (alias: control)
  ctrl（别名：control）
• alt (aliases: opt, option) — note: alt and meta are identical in terminals
  alt（别名：opt、option）——注意：在终端中 alt 与 meta 完全相同
• shift
shift
• meta (aliases: cmd, command)
  meta（别名：cmd、command）

Special keys: escape/esc, enter/return, tab, space, backspace, delete, up, down, left, right

特殊键：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)

组合键（chord）：以空格分隔的按键序列，例如 ctrl+k ctrl+s（两次按键之间超时 1 秒）

Examples: ctrl+shift+p, alt+enter, ctrl+k ctrl+n

示例：ctrl+shift+p、alt+enter、ctrl+k ctrl+n

Unbinding Default Shortcuts / 解绑默认快捷键

Set a key to null to remove its default binding:

将某个键设为 null 即可移除其默认绑定：

{
  "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
  要把绑定移动到另一个键：先解绑旧键（设为 null），再添加新绑定
• 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:
要把外部编辑器快捷键从 ctrl+g 改为 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)
   如果用户选择的键与保留快捷键或 tmux（ctrl+b）、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.

Claude Code 在加载时会校验 ~/.claude/keybindings.json；警告会写入调试日志。编辑该文件后，按下方规则重新检查并修复所有匹配的问题。

Common Issues and Fixes / 常见问题与修复

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.

**错误（error）**会使绑定无法工作，必须修复。**警告（warning）**表示存在潜在冲突，但绑定可能仍然有效。

Reserved Shortcuts / 保留快捷键

Non-rebindable (errors) / 不可重绑定（报错）

• ctrl+c — Cannot be rebound - used for interrupt/exit (hardcoded)
  ctrl+c —— 不可重绑定——用于中断/退出（硬编码）
• ctrl+d — Cannot be rebound - used for exit (hardcoded)
  ctrl+d —— 不可重绑定——用于退出（硬编码）
• ctrl+m — Cannot be rebound - identical to Enter in terminals (both send CR)
  ctrl+m —— 不可重绑定——在终端中与 Enter 相同（都发送 CR）
• ctrl+[ — Cannot be rebound - identical to Escape in terminals
  ctrl+[ —— 不可重绑定——在终端中与 Escape 相同
• ctrl+i — Cannot be rebound - identical to Tab in terminals
  ctrl+i —— 不可重绑定——在终端中与 Tab 相同
• ctrl+h — Cannot be rebound - identical to Backspace in terminals
  ctrl+h —— 不可重绑定——在终端中与 Backspace 相同
• capslock — Caps Lock is not delivered to terminal applications
  capslock —— Caps Lock 不会传递给终端应用

Terminal reserved (errors/warnings) / 终端保留（报错/警告）

• ctrl+z — Unix process suspend (SIGTSTP) (may conflict)
  ctrl+z —— Unix 进程挂起（SIGTSTP）（可能冲突）
• ctrl+\ — Terminal quit signal (SIGQUIT) (will not work)
  ctrl+\ —— 终端退出信号（SIGQUIT）（不会生效）

macOS reserved (errors) / macOS 保留（报错）

• cmd+c — macOS system copy
  cmd+c —— macOS 系统复制
• cmd+v — macOS system paste
  cmd+v —— macOS 系统粘贴
• cmd+x — macOS system cut
  cmd+x —— macOS 系统剪切
• cmd+q — macOS quit application
  cmd+q —— macOS 退出应用
• cmd+w — macOS close window/tab
  cmd+w —— macOS 关闭窗口/标签页
• cmd+tab — macOS app switcher
  cmd+tab —— macOS 应用切换器
• cmd+space — macOS Spotlight
  cmd+space —— macOS Spotlight

Available Contexts / 可用上下文

Available Actions / 可用动作