keybindings.ts
1 import { DEFAULT_BINDINGS } from '../../keybindings/defaultBindings.js' 2 import { isKeybindingCustomizationEnabled } from '../../keybindings/loadUserBindings.js' 3 import { 4 MACOS_RESERVED, 5 NON_REBINDABLE, 6 TERMINAL_RESERVED, 7 } from '../../keybindings/reservedShortcuts.js' 8 import type { KeybindingsSchemaType } from '../../keybindings/schema.js' 9 import { 10 KEYBINDING_ACTIONS, 11 KEYBINDING_CONTEXT_DESCRIPTIONS, 12 KEYBINDING_CONTEXTS, 13 } from '../../keybindings/schema.js' 14 import { jsonStringify } from '../../utils/slowOperations.js' 15 import { registerBundledSkill } from '../bundledSkills.js' 16 17 /** 18 * Build a markdown table of all contexts. 19 */ 20 function generateContextsTable(): string { 21 return markdownTable( 22 ['Context', 'Description'], 23 KEYBINDING_CONTEXTS.map(ctx => [ 24 `\`${ctx}\``, 25 KEYBINDING_CONTEXT_DESCRIPTIONS[ctx], 26 ]), 27 ) 28 } 29 30 /** 31 * Build a markdown table of all actions with their default bindings and context. 32 */ 33 function generateActionsTable(): string { 34 // Build a lookup: action -> { keys, context } 35 const actionInfo: Record<string, { keys: string[]; context: string }> = {} 36 for (const block of DEFAULT_BINDINGS) { 37 for (const [key, action] of Object.entries(block.bindings)) { 38 if (action) { 39 if (!actionInfo[action]) { 40 actionInfo[action] = { keys: [], context: block.context } 41 } 42 actionInfo[action].keys.push(key) 43 } 44 } 45 } 46 47 return markdownTable( 48 ['Action', 'Default Key(s)', 'Context'], 49 KEYBINDING_ACTIONS.map(action => { 50 const info = actionInfo[action] 51 const keys = info ? info.keys.map(k => `\`${k}\``).join(', ') : '(none)' 52 const context = info ? info.context : inferContextFromAction(action) 53 return [`\`${action}\``, keys, context] 54 }), 55 ) 56 } 57 58 /** 59 * Infer context from action prefix when not in DEFAULT_BINDINGS. 60 */ 61 function inferContextFromAction(action: string): string { 62 const prefix = action.split(':')[0] 63 const prefixToContext: Record<string, string> = { 64 app: 'Global', 65 history: 'Global or Chat', 66 chat: 'Chat', 67 autocomplete: 'Autocomplete', 68 confirm: 'Confirmation', 69 tabs: 'Tabs', 70 transcript: 'Transcript', 71 historySearch: 'HistorySearch', 72 task: 'Task', 73 theme: 'ThemePicker', 74 help: 'Help', 75 attachments: 'Attachments', 76 footer: 'Footer', 77 messageSelector: 'MessageSelector', 78 diff: 'DiffDialog', 79 modelPicker: 'ModelPicker', 80 select: 'Select', 81 permission: 'Confirmation', 82 } 83 return prefixToContext[prefix ?? ''] ?? 'Unknown' 84 } 85 86 /** 87 * Build a list of reserved shortcuts. 88 */ 89 function generateReservedShortcuts(): string { 90 const lines: string[] = [] 91 92 lines.push('### Non-rebindable (errors)') 93 for (const s of NON_REBINDABLE) { 94 lines.push(`- \`${s.key}\` — ${s.reason}`) 95 } 96 97 lines.push('') 98 lines.push('### Terminal reserved (errors/warnings)') 99 for (const s of TERMINAL_RESERVED) { 100 lines.push( 101 `- \`${s.key}\` — ${s.reason} (${s.severity === 'error' ? 'will not work' : 'may conflict'})`, 102 ) 103 } 104 105 lines.push('') 106 lines.push('### macOS reserved (errors)') 107 for (const s of MACOS_RESERVED) { 108 lines.push(`- \`${s.key}\` — ${s.reason}`) 109 } 110 111 return lines.join('\n') 112 } 113 114 const FILE_FORMAT_EXAMPLE: KeybindingsSchemaType = { 115 $schema: 'https://www.schemastore.org/claude-code-keybindings.json', 116 $docs: 'https://code.claude.com/docs/en/keybindings', 117 bindings: [ 118 { 119 context: 'Chat', 120 bindings: { 121 'ctrl+e': 'chat:externalEditor', 122 }, 123 }, 124 ], 125 } 126 127 const UNBIND_EXAMPLE: KeybindingsSchemaType['bindings'][number] = { 128 context: 'Chat', 129 bindings: { 130 'ctrl+s': null, 131 }, 132 } 133 134 const REBIND_EXAMPLE: KeybindingsSchemaType['bindings'][number] = { 135 context: 'Chat', 136 bindings: { 137 'ctrl+g': null, 138 'ctrl+e': 'chat:externalEditor', 139 }, 140 } 141 142 const CHORD_EXAMPLE: KeybindingsSchemaType['bindings'][number] = { 143 context: 'Global', 144 bindings: { 145 'ctrl+k ctrl+t': 'app:toggleTodos', 146 }, 147 } 148 149 const SECTION_INTRO = [ 150 '# Keybindings Skill', 151 '', 152 'Create or modify `~/.claude/keybindings.json` to customize keyboard shortcuts.', 153 '', 154 '## CRITICAL: Read Before Write', 155 '', 156 '**Always read `~/.claude/keybindings.json` first** (it may not exist yet). Merge changes with existing bindings — never replace the entire file.', 157 '', 158 '- Use **Edit** tool for modifications to existing files', 159 '- Use **Write** tool only if the file does not exist yet', 160 ].join('\n') 161 162 const SECTION_FILE_FORMAT = [ 163 '## File Format', 164 '', 165 '```json', 166 jsonStringify(FILE_FORMAT_EXAMPLE, null, 2), 167 '```', 168 '', 169 'Always include the `$schema` and `$docs` fields.', 170 ].join('\n') 171 172 const SECTION_KEYSTROKE_SYNTAX = [ 173 '## Keystroke Syntax', 174 '', 175 '**Modifiers** (combine with `+`):', 176 '- `ctrl` (alias: `control`)', 177 '- `alt` (aliases: `opt`, `option`) — note: `alt` and `meta` are identical in terminals', 178 '- `shift`', 179 '- `meta` (aliases: `cmd`, `command`)', 180 '', 181 '**Special keys**: `escape`/`esc`, `enter`/`return`, `tab`, `space`, `backspace`, `delete`, `up`, `down`, `left`, `right`', 182 '', 183 '**Chords**: Space-separated keystrokes, e.g. `ctrl+k ctrl+s` (1-second timeout between keystrokes)', 184 '', 185 '**Examples**: `ctrl+shift+p`, `alt+enter`, `ctrl+k ctrl+n`', 186 ].join('\n') 187 188 const SECTION_UNBINDING = [ 189 '## Unbinding Default Shortcuts', 190 '', 191 'Set a key to `null` to remove its default binding:', 192 '', 193 '```json', 194 jsonStringify(UNBIND_EXAMPLE, null, 2), 195 '```', 196 ].join('\n') 197 198 const SECTION_INTERACTION = [ 199 '## How User Bindings Interact with Defaults', 200 '', 201 '- User bindings are **additive** — they are appended after the default bindings', 202 '- To **move** a binding to a different key: unbind the old key (`null`) AND add the new binding', 203 "- A context only needs to appear in the user's file if they want to change something in that context", 204 ].join('\n') 205 206 const SECTION_COMMON_PATTERNS = [ 207 '## Common Patterns', 208 '', 209 '### Rebind a key', 210 'To change the external editor shortcut from `ctrl+g` to `ctrl+e`:', 211 '```json', 212 jsonStringify(REBIND_EXAMPLE, null, 2), 213 '```', 214 '', 215 '### Add a chord binding', 216 '```json', 217 jsonStringify(CHORD_EXAMPLE, null, 2), 218 '```', 219 ].join('\n') 220 221 const SECTION_BEHAVIORAL_RULES = [ 222 '## Behavioral Rules', 223 '', 224 '1. Only include contexts the user wants to change (minimal overrides)', 225 '2. Validate that actions and contexts are from the known lists below', 226 '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`)', 227 '4. When adding a new binding for an existing action, the new binding is additive (existing default still works unless explicitly unbound)', 228 '5. To fully replace a default binding, unbind the old key AND add the new one', 229 ].join('\n') 230 231 const SECTION_DOCTOR = [ 232 '## Validation with /doctor', 233 '', 234 'The `/doctor` command includes a "Keybinding Configuration Issues" section that validates `~/.claude/keybindings.json`.', 235 '', 236 '### Common Issues and Fixes', 237 '', 238 markdownTable( 239 ['Issue', 'Cause', 'Fix'], 240 [ 241 [ 242 '`keybindings.json must have a "bindings" array`', 243 'Missing wrapper object', 244 'Wrap bindings in `{ "bindings": [...] }`', 245 ], 246 [ 247 '`"bindings" must be an array`', 248 '`bindings` is not an array', 249 'Set `"bindings"` to an array: `[{ context: ..., bindings: ... }]`', 250 ], 251 [ 252 '`Unknown context "X"`', 253 'Typo or invalid context name', 254 'Use exact context names from the Available Contexts table', 255 ], 256 [ 257 '`Duplicate key "X" in Y bindings`', 258 'Same key defined twice in one context', 259 'Remove the duplicate; JSON uses only the last value', 260 ], 261 [ 262 '`"X" may not work: ...`', 263 'Key conflicts with terminal/OS reserved shortcut', 264 'Choose a different key (see Reserved Shortcuts section)', 265 ], 266 [ 267 '`Could not parse keystroke "X"`', 268 'Invalid key syntax', 269 'Check syntax: use `+` between modifiers, valid key names', 270 ], 271 [ 272 '`Invalid action for "X"`', 273 'Action value is not a string or null', 274 'Actions must be strings like `"app:help"` or `null` to unbind', 275 ], 276 ], 277 ), 278 '', 279 '### Example /doctor Output', 280 '', 281 '```', 282 'Keybinding Configuration Issues', 283 'Location: ~/.claude/keybindings.json', 284 ' └ [Error] Unknown context "chat"', 285 ' → Valid contexts: Global, Chat, Autocomplete, ...', 286 ' └ [Warning] "ctrl+c" may not work: Terminal interrupt (SIGINT)', 287 '```', 288 '', 289 '**Errors** prevent bindings from working and must be fixed. **Warnings** indicate potential conflicts but the binding may still work.', 290 ].join('\n') 291 292 export function registerKeybindingsSkill(): void { 293 registerBundledSkill({ 294 name: 'keybindings-help', 295 description: 296 '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".', 297 allowedTools: ['Read'], 298 userInvocable: false, 299 isEnabled: isKeybindingCustomizationEnabled, 300 async getPromptForCommand(args) { 301 // Generate reference tables dynamically from source-of-truth arrays 302 const contextsTable = generateContextsTable() 303 const actionsTable = generateActionsTable() 304 const reservedShortcuts = generateReservedShortcuts() 305 306 const sections = [ 307 SECTION_INTRO, 308 SECTION_FILE_FORMAT, 309 SECTION_KEYSTROKE_SYNTAX, 310 SECTION_UNBINDING, 311 SECTION_INTERACTION, 312 SECTION_COMMON_PATTERNS, 313 SECTION_BEHAVIORAL_RULES, 314 SECTION_DOCTOR, 315 `## Reserved Shortcuts\n\n${reservedShortcuts}`, 316 `## Available Contexts\n\n${contextsTable}`, 317 `## Available Actions\n\n${actionsTable}`, 318 ] 319 320 if (args) { 321 sections.push(`## User Request\n\n${args}`) 322 } 323 324 return [{ type: 'text', text: sections.join('\n\n') }] 325 }, 326 }) 327 } 328 329 /** 330 * Build a markdown table from headers and rows. 331 */ 332 function markdownTable(headers: string[], rows: string[][]): string { 333 const separator = headers.map(() => '---') 334 return [ 335 `| ${headers.join(' | ')} |`, 336 `| ${separator.join(' | ')} |`, 337 ...rows.map(row => `| ${row.join(' | ')} |`), 338 ].join('\n') 339 }