change-keybinding

name	change-keybinding
description	Customize CastCodes keyboard shortcuts (keybindings, keymappings) by editing the user's keybindings.yaml file. Use when the user asks to remap a key combination, rebind an action, change a shortcut, or remove a default keybinding (e.g. "change ctrl+space to ctrl+s", "rebind the command palette to cmd+p", "remove the default for X").

change-keybinding

Use this skill when the user wants to remap, rebind, or remove a CastCodes keyboard shortcut.

Keybindings file

User customizations live at:

{{keybindings_file_path}}

This is the exact path CastCodes reads at launch and it is platform- and channel-specific. Use this path verbatim; do not infer a different one from the user's home directory layout. Create the file and any missing parent directories if it does not exist.

File format

A flat YAML map of action_name → key_trigger. Action names contain a colon, so they must be quoted:

"workspace:toggle_ai_assistant": ctrl-s
"editor_view:delete_all_left": cmd-shift-A
"workspace:toggle_command_palette": none

Keystroke encoding rules

Triggers use CastCodes' normalized form — get this exactly right or the binding silently fails to load.

• Modifiers (in this order when combined): ctrl-alt-shift-cmd-meta-. Cross-platform alias: cmdorctrl- (becomes cmd on macOS, ctrl elsewhere).
• Letter casing: applies only to single-letter keys. Without shift, the letter is lowercase (ctrl-s). With shift, the letter is uppercase (shift-A, never shift-a). Mixing them is invalid.
• Special keys: space, enter, escape, tab, backspace, delete, insert, up, down, left, right, home, end, pageup, pagedown, f1–f20, numpadenter. Always lowercase, even with shift (ctrl-shift-space, shift-tab — never ctrl-shift-SPACE). Use the literal word space — not " ".
• Punctuation is the bare character: cmd-=, cmd-,, cmdorctrl-/.
• Remove a default binding: set the value to the literal string none. The action becomes unbound.

Translate user phrasing into this form: Ctrl+S → ctrl-s, Cmd+Shift+P → cmd-shift-P, Ctrl+Space → ctrl-space.

Identifying the action

Defaults are compiled into CastCodes and are not discoverable from the keybindings file on disk. There is no catalog the agent can consult to map a description or current shortcut to an action name. Pick the right strategy based on how the user described the change:

1. By action name ("set workspace:toggle_command_palette to cmd-p"): the user already gave you the name — write it directly.

2. By description or current key combo ("rebind the command palette to cmd-p", "change ctrl+space to ctrl+s"): you don't have the action name and cannot reliably guess it. Do not invent one. Direct the user to the keybindings editor (workspace:show_keybinding_settings, default cmd-ctrl-k on macOS; Settings → Keyboard Shortcuts on other platforms) — they can search by description or current shortcut there and either edit the binding in place or share the canonical namespace:action_name so you can write it.

Workflow

1. Determine which action to remap and the new trigger (see "Identifying the action").
2. Read the existing keybindings file at {{keybindings_file_path}} if present. Preserve every existing entry — only add or update the one you're changing.
3. Write the file (creating parent directories if necessary). Make sure the action key is quoted and the value is normalized (see encoding rules).
4. Tell the user that CastCodes must be restarted for the change to take effect — the keybindings file is loaded only at app launch, unlike settings.toml which hot-reloads. They can quit with cmd-Q (macOS) or the equivalent on their platform and reopen CastCodes.

Examples

Remap an existing custom binding by old trigger:

# before
"workspace:toggle_ai_assistant": ctrl-space
# after
"workspace:toggle_ai_assistant": ctrl-s

Remove a default shortcut:

"workspace:toggle_keybindings_page": none

Shift combined with a special key (note the special key stays lowercase):

"workspace:toggle_ai_assistant": ctrl-shift-space

Cross-platform binding using the cmdorctrl- alias (resolves to cmd on macOS, ctrl elsewhere):

"workspace:toggle_command_palette": cmdorctrl-shift-P