cmux-keyboard-shortcuts

cmux-keyboard-shortcuts

Use this skill to turn a user's workflow preferences into cmux shortcut bindings in ~/.config/cmux/cmux.json. It should guide the user, propose compact templates, apply selected changes, and confirm the config parses with recognized keys.

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.
• For action IDs, read skills/cmux-settings/references/shortcut-actions.md.
• For current defaults, read web/data/cmux-shortcuts.ts or Sources/KeyboardShortcutSettings.swift.

find_cmux_settings() {
  local root
  root="$(git -C "$(pwd)" 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
    if [[ -x "$candidate" ]]; then
      printf '%s\n' "$candidate"
      return 0
    fi
  done
  return 1
}

if [[ -z "${CMUX_SETTINGS:-}" ]]; then
  CMUX_SETTINGS="$(find_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 and selectWorkspaceByNumber must use a digit from 1 to 9. cmd+1 means the full cmd+1 through cmd+9 family.
• showHideAllWindows and globalSearch are system-wide shortcuts. They cannot be chords, require modifiers, and may be rejected by macOS if reserved.
• 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. Do not tell the user to restart cmux.