/cmux-keyboard-shortcuts

name: cmux-keyboard-shortcuts
description: "Guide and apply cmux keyboard shortcut customization. Use when the user asks to customize, rebind, unbind, reset, audit, or create shortcut templates for cmux, including tmux-style, Vim-style, terminal-first, browser-heavy, iTerm/Terminal-like, or agent-triage layouts."

cmux-keyboard-shortcuts

Turn a user's workflow preferences into cmux shortcut bindings in `~/.config/cmux/cmux.json`: guide, propose compact templates, apply the selected changes, and confirm the config parses with recognized keys.

Contributor rule: adding a new shortcut

Every new cmux-owned keyboard shortcut must be added to `Sources/KeyboardShortcutSettings.swift`, visible and editable in Settings > Keyboard Shortcuts, supported as `shortcuts.bindings.<actionId>` in `~/.config/cmux/cmux.json`, and documented in `web/app/[locale]/(landing)/docs/keyboard-shortcuts/page.tsx` and the configuration docs. All four, not a subset.

Prerequisites

• Work from a cmux checkout or worktree root when possible.
• Use `skills/cmux-settings/scripts/cmux-settings` for every read/write. It reads JSONC, writes atomically, and validates JSON plus recognized settings keys.
• Action IDs: `skills/cmux-settings/references/shortcut-actions.md`. Current defaults: `web/data/cmux-shortcuts.ts` or `Sources/KeyboardShortcutSettings.swift`.

if [[ -z "${CMUX_SETTINGS:-}" ]]; then
  root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
  for candidate in \
    "$root/skills/cmux-settings/scripts/cmux-settings" \
    "${CODEX_HOME:-$HOME/.codex}/skills/cmux-settings/scripts/cmux-settings" \
    "$HOME/.agents/skills/cmux-settings/scripts/cmux-settings"; do
    [[ -x "$candidate" ]] && CMUX_SETTINGS="$candidate" && break
  done
  [[ -n "${CMUX_SETTINGS:-}" ]] || {
    echo "cmux-settings helper not found; run from a cmux checkout or install cmux-settings" >&2
    exit 1
  }
fi

Shortcut model

• Setting path: `shortcuts.bindings.<actionId>`.
• Single stroke: `"cmd+b"`.
• Chord: `["ctrl+b","c"]`. The first stroke needs a modifier unless the key is Space. The second stroke can be bare.
• Unbind: prefer `null` for explicit unbinds. `""`, `"none"`, `"clear"`, `"unbound"`, and `"disabled"` are accepted aliases, but `null` is the clearest JSON value and matches the templates below.
• `selectSurfaceByNumber`, `selectWorkspaceByNumber` and `focusPaneByNumber` must use a digit from 1 to 9. `cmd+1` means the full `cmd+1` through `cmd+9` family.
• `showHideAllWindows` is the only system-wide shortcut. It cannot be a chord, requires modifiers, and may be rejected by macOS if reserved.
• `globalSearch` is application-scoped and only fires while cmux is active.
• `showHideAllWindows` also requires Settings > Global Hotkey > Enable System-Wide Hotkey. The binding can validate in `cmux.json` while the feature is disabled, so warn the user to enable that setting before reporting the shortcut as usable.
• `unset` deletes a `cmux.json` override. It does not clear shortcut changes saved through the Settings UI/UserDefaults. If the user asks for true built-in defaults, tell them to use Settings > Keyboard Shortcuts > Reset Default Shortcuts after clearing file-managed overrides, then verify in the app. For `showHideAllWindows`, use Settings > Global Hotkey to restore the shortcut to `ctrl+opt+cmd+.` because Keyboard Shortcuts > Reset Default Shortcuts intentionally skips the global hotkey.
• Saving `cmux.json` live reloads. Never tell the user to restart cmux.

Workflow

1. Classify the request:

• **One-off rebind/unbind:** map the phrase to an action ID, apply, validate, report previous and new binding.
• **Audit:** inspect bindings, validate, summarize overrides and unbound shortcuts without writing.
• **Reset:** clarify file-managed overrides vs true built-in defaults (see the `unset` rule above).
• **Broad customization:** propose 3-5 templates below and ask the user to choose.
• **Named style** (tmux, Vim, iTerm, browser, agent triage): pick the closest template, show the changed actions and likely collisions, and ask before a bulk apply unless the user already named that template.

2. Inspect existing config:

   "$CMUX_SETTINGS" path
   "$CMUX_SETTINGS" get shortcuts.bindings 2>/dev/null || printf '{}\n'
   "$CMUX_SETTINGS" validate

3. Snapshot prior values for every action you will change. A path that was absent reverts with `unset`; a path with an existing custom value reverts with `set <same-json-value>`.

   "$CMUX_SETTINGS" get shortcuts.bindings.focusLeft 2>/dev/null || printf '<absent>\n'

4. Apply only the chosen action paths, then `"$CMUX_SETTINGS" validate`.

   "$CMUX_SETTINGS" set shortcuts.bindings.newSurface '["ctrl+b","c"]'
   "$CMUX_SETTINGS" set shortcuts.bindings.focusLeft cmd+opt+h
   "$CMUX_SETTINGS" set shortcuts.bindings.sendFeedback null

5. Read back each changed action: `"$CMUX_SETTINGS" get shortcuts.bindings.newSurface`. 6. Finish with the template name, changed actions, and exact revert commands from the snapshot.

Preset templates

Settings > Keyboard Shortcuts > Base Keymap (also "Base Keymap: ..." in the Command Palette) ships cmux, iTerm2, Terminal.app, and tmux-style presets. It previews the change, then writes only the overrides that differ from cmux defaults, keeps bindings the user set by hand (in `cmux.json` or legacy Settings UserDefaults), and lists macOS shortcut conflicts. Detection is stateless: a binding typed by hand that equals a preset's value for that action is treated as the preset's, so switching presets (including back to cmux) replaces or removes it. Point users there for those styles; use the templates below for the others.

Apply action by action, never by overwriting the whole `shortcuts.bindings` object.

Tmux Prefix

One terminal-style namespace; `ctrl+b` starts a cmux chord instead of reaching the shell.

"$CMUX_SETTINGS" set shortcuts.binding