cmux-keyboard-shortcuts

Source excerpt starting at line 1.

1---2name: cmux-keyboard-shortcuts3description: "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."4---5 6# cmux-keyboard-shortcuts7 8Turn 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.9 10## Contributor rule: adding a new shortcut11 12Every 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.13 14## Prerequisites15 16- Work from a cmux checkout or worktree root when possible.17- Use `skills/cmux-settings/scripts/cmux-settings` for every read/write. It reads JSONC, writes atomically, and validates JSON plus recognized settings keys.18- Action IDs: `skills/cmux-settings/references/shortcut-actions.md`. Current defaults: `web/data/cmux-shortcuts.ts` or `Sources/KeyboardShortcutSettings.swift`.19 20```bash21if [[ -z "${CMUX_SETTINGS:-}" ]]; then22  root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"23  for candidate in \24    "$root/skills/cmux-settings/scripts/cmux-settings" \25    "${CODEX_HOME:-$HOME/.codex}/skills/cmux-settings/scripts/cmux-settings" \26    "$HOME/.agents/skills/cmux-settings/scripts/cmux-settings"; do27    [[ -x "$candidate" ]] && CMUX_SETTINGS="$candidate" && break28  done29  [[ -n "${CMUX_SETTINGS:-}" ]] || {30    echo "cmux-settings helper not found; run from a cmux checkout or install cmux-settings" >&231    exit 132  }33fi34```35 36## Shortcut model37 38- Setting path: `shortcuts.bindings.<actionId>`.39- Single stroke: `"cmd+b"`.40- Chord: `["ctrl+b","c"]`. The first stroke needs a modifier unless the key is Space. The second stroke can be bare.41- 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.42- `selectSurfaceByNumber` and `selectWorkspaceByNumber` must use a digit from 1 to 9. `cmd+1` means the full `cmd+1` through `cmd+9` family.43- `showHideAllWindows` is the only system-wide shortcut. It cannot be a chord, requires modifiers, and may be rejected by macOS if reserved.44- `globalSearch` is application-scoped and only fires while cmux is active.45- `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.46- `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.47- Saving `cmux.json` live reloads. Never tell the user to restart cmux.48 49## Workflow50 511. Classify the request:52   - **One-off rebind/unbind:** map the phrase to an action ID, apply, validate, report previous and new binding.53   - **Audit:** inspect bindings, validate, summarize overrides and unbound shortcuts without writing.54   - **Reset:** clarify file-managed overrides vs true built-in defaults (see the `unset` rule above).55   - **Broad customization:** propose 3-5 templates below and ask the user to choose.56   - **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.572. Inspect existing config:58 59   ```bash60   "$CMUX_SETTINGS" path61   "$CMUX_SETTINGS" get shortcuts.bindings 2>/dev/null || printf '{}\n'62   "$CMUX_SETTINGS" validate63   ```64 653. 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>`.66 67   ```bash68   "$CMUX_SETTINGS" get shortcuts.bindings.focusLeft 2>/dev/null || printf '<absent>\n'69   ```70 714. Apply only the chosen action paths, then `"$CMUX_SETTINGS" validate`.72 73   ```bash74   "$CMUX_SETTINGS" set shortcuts.bindings.newSurface '["ctrl+b","c"]'75   "$CMUX_SETTINGS" set shortcuts.bindings.focusLeft cmd+opt+h76   "$CMUX_SETTINGS" set shortcuts.bindings.sendFeedback null77   ```78 795. Read back each changed action: `"$CMUX_SETTINGS" get shortcuts.bindings.newSurface`.806. Finish with the template name, changed actions, and exact revert commands from the snapshot.81 82## Preset templates83 84Apply action by action, never by overwriting the whole `shortcuts.bindings` object.85 86### Tmux Prefix87 88One terminal-style namespace; `ctrl+b` starts a cmux chord instead of reaching the shell.89 90```bash91"$CMUX_SETTINGS" set shortcuts.bindings.newSurface '["ctrl+b","c"]'92"$CMUX_SETTINGS" set shortcuts.bindings.closeTab '["ctrl+b","x"]'93"$CMUX_SETTINGS" set shortcuts.bindings.nextSurface '["ctrl+b","n"]'94"$CMUX_SETTINGS" set shortcuts.bindings.prevSurface '["ctrl+b","p"]'95"$CMUX_SETTINGS" set shortcuts.bindings.selectSurfaceByNumber '["ctrl+b","1"]'96"$CMUX_SETTINGS" set shortcuts.bindings.splitRight '["ctrl+b","v"]'97"$CMUX_SETTINGS" set shortcuts.bindings.splitDown '["ctrl+b","s"]'98"$CMUX_SETTINGS" set shortcuts.bindings.focusLeft '["ctrl+b","h"]'99"$CMUX_SETTINGS" set shortcuts.bindings.focusDown '["ctrl+b","j"]'100"$CMUX_SETTINGS" set shortcuts.bindings.focusUp '["ctrl+b","k"]'101"$CMUX_SETTINGS" set shortcuts.bindings.focusRight '["ctrl+b","l"]'102"$CMUX_SETTINGS" set shortcuts.bindings.toggleSplitZoom '["ctrl+b","z"]'103"$CMUX_SETTINGS" set shortcuts.bindings.toggleTerminalCopyMode '["ctrl+b","["]'104"$CMUX_SETTINGS" set shortcuts.bindings.equalizeSplits '["ctrl+b","="]'105```106 107### macOS Terminal/iTerm Restore108 109These actions already match cmux built-in defaults, so clear file overrides rather than writing default values.110 111```bash112for a in newSurface closeTab nextSurface prevSurface selectSurfaceByNumber \113         splitRight splitDown toggleSplitZoom toggleTerminalCopyMode renameTab; do114  "$CMUX_SETTINGS" unset "shortcuts.bindings.$a"115done116```117 118### Vim Pane Navigation119 120Prefix-free pane movement with no arrow keys.121 122```bash123"$CMUX_SETTINGS" set shortcuts.bindings.focusLeft cmd+opt+h124"$CMUX_SETTINGS" set shortcuts.bindings.focusDown cmd+opt+j125"$CMUX_SETTINGS" set shortcuts.bindings.focusUp cmd+opt+k126"$CMUX_SETTINGS" set shortcuts.bindings.focusRight cmd+opt+l127"$CMUX_SETTINGS" set shortcuts.bindings.splitRight cmd+opt+v128"$CMUX_SETTINGS" set shortcuts.bindings.splitDown cmd+opt+s129"$CMUX_SETTINGS" set shortcuts.bindings.toggleSplitZoom cmd+opt+z130"$CMUX_SETTINGS" set shortcuts.bindings.equalizeSplits cmd+opt+=131```132 133### Agent Triage134 135Unread handling on one key family. `toggleUnread` stays on `cmd+opt+u` so this composes with Vim Pane Navigation without colliding with `cmd+opt+j`.136 137```bash138"$CMUX_SETTINGS" set shortcuts.bindings.showNotifications cmd+u139"$CMUX_SETTINGS" set shortcuts.bindings.jumpToUnread cmd+j140"$CMUX_SETTINGS" set shortcuts.bindings.markOldestUnreadAndJumpNext cmd+shift+j141"$CMUX_SETTINGS" set shortcuts.bindings.toggleUnread cmd+opt+u142"$CMUX_SETTINGS" set shortcuts.bindings.triggerFlash cmd+shift+h143"$CMUX_SETTINGS" set shortcuts.bindings.focusRightSidebar cmd+shift+e144```145 146### Workspace And Surface Lanes147 148Workspaces and surfaces on distinct number and bracket lanes.149 150```bash151"$CMUX_SETTINGS" set shortcuts.bindings.selectWorkspaceByNumber cmd+1152"$CMUX_SETTINGS" set shortcuts.bindings.selectSurfaceByNumber cmd+opt+1153"$CMUX_SETTINGS" set shortcuts.bindings.nextSidebarTab 'cmd+opt+]'154"$CMUX_SETTINGS" set shortcuts.bindings.prevSidebarTab 'cmd+opt+['155"$CMUX_SETTINGS" set shortcuts.bindings.nextSurface 'cmd+shift+]'156"$CMUX_SETTINGS" set shortcuts.bindings.prevSurface 'cmd+shift+['157```158 159### Browser Defaults Restore160 161Return embedded-browser behavior to common macOS browser shortcuts. `unset` keeps future cmux defaults applying.162 163```bash164for a in openBrowser focusBrowserAddressBar browserBack browserForward browserReload \165         browserZoomIn browserZoomOut browserZoomReset toggleBrowserDeveloperTools \166         showBrowserJavaScriptConsole find findNext findPrevious; do167  "$CMUX_SETTINGS" unset "shortcuts.bindings.$a"168done169```170 171### Terminal-First Cleanup172 173Fewer app-level shortcuts. Prefer unbinding only the actions the user names; this is a starting proposal.174 175```bash176for a in renameTab renameWorkspace editWorkspaceDescription triggerFlash sendFeedback; do177  "$CMUX_SETTINGS" set "shortcuts.bindings.$a" null178done179```180 181## Rules182 183- Do not edit `~/.config/cmux/settings.json` unless the user explicitly asks; it is legacy fallback config.184- Do not overwrite all of `shortcuts.bindings` unless the user wants a full replacement.185- Do not invent action IDs. Validate against the schema or `shortcut-actions.md`.186- Do not apply a broad template without showing the changed actions first, unless the user named that template.187- Do not promise conflict detection from `cmux-settings validate`. It validates JSON and supported keys, not shortcut syntax, macOS reservation, or focus-context conflicts.188- Before assigning `cmd+[` or `cmd+]` to application-scoped actions, warn that they collide with browser Back/Forward unless the browser actions are also changed or unbound.189- `unset` clears file-managed overrides for one action. Do not call that a built-in default reset unless Settings UI/UserDefaults values were also reset.190