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.bindings.newSurface '["ctrl+b","c"]'
"$CMUX_SETTINGS" set shortcuts.bindings.closeTab '["ctrl+b","x"]'
"$CMUX_SETTINGS" set shortcuts.bindings.nextSurface '["ctrl+b","n"]'
"$CMUX_SETTINGS" set shortcuts.bindings.prevSurface '["ctrl+b","p"]'
"$CMUX_SETTINGS" set shortcuts.bindings.selectSurfaceByNumber '["ctrl+b","1"]'
"$CMUX_SETTINGS" set shortcuts.bindings.splitRight '["ctrl+b","v"]'
"$CMUX_SETTINGS" set shortcuts.bindings.splitDown '["ctrl+b","s"]'
"$CMUX_SETTINGS" set shortcuts.bindings.focusLeft '["ctrl+b","h"]'
"$CMUX_SETTINGS" set shortcuts.bindings.focusDown '["ctrl+b","j"]'
"$CMUX_SETTINGS" set shortcuts.bindings.focusUp '["ctrl+b","k"]'
"$CMUX_SETTINGS" set shortcuts.bindings.focusRight '["ctrl+b","l"]'
"$CMUX_SETTINGS" set shortcuts.bindings.toggleSplitZoom '["ctrl+b","z"]'
"$CMUX_SETTINGS" set shortcuts.bindings.toggleTerminalCopyMode '["ctrl+b","["]'
"$CMUX_SETTINGS" set shortcuts.bindings.equalizeSplits '["ctrl+b","="]'

macOS Terminal/iTerm Restore

These actions already match cmux built-in defaults, so clear file overrides rather than writing default values.

for a in newSurface closeTab nextSurface prevSurface selectSurfaceByNumber \
         splitRight splitDown toggleSplitZoom toggleTerminalCopyMode renameTab; do
  "$CMUX_SETTINGS" unset "shortcuts.bindings.$a"
done

Vim Pane Navigation

Prefix-free pane movement with no arrow keys.

"$CMUX_SETTINGS" set shortcuts.bindings.focusLeft cmd+opt+h
"$CMUX_SETTINGS" set shortcuts.bindings.focusDown cmd+opt+j
"$CMUX_SETTINGS" set shortcuts.bindings.focusUp cmd+opt+k
"$CMUX_SETTINGS" set shortcuts.bindings.focusRight cmd+opt+l
"$CMUX_SETTINGS" set shortcuts.bindings.splitRight cmd+opt+v
"$CMUX_SETTINGS" set shortcuts.bindings.splitDown cmd+opt+s
"$CMUX_SETTINGS" set shortcuts.bindings.toggleSplitZoom cmd+opt+z
"$CMUX_SETTINGS" set shortcuts.bindings.equalizeSplits cmd+opt+=

Agent Triage

Unread handling on one key family. toggleUnread stays on cmd+opt+u so this composes with Vim Pane Navigation without colliding with cmd+opt+j.

"$CMUX_SETTINGS" set shortcuts.bindings.showNotifications cmd+u
"$CMUX_SETTINGS" set shortcuts.bindings.jumpToUnread cmd+j
"$CMUX_SETTINGS" set shortcuts.bindings.markOldestUnreadAndJumpNext cmd+shift+j
"$CMUX_SETTINGS" set shortcuts.bindings.toggleUnread cmd+opt+u
"$CMUX_SETTINGS" set shortcuts.bindings.triggerFlash cmd+shift+h
"$CMUX_SETTINGS" set shortcuts.bindings.focusRightSidebar cmd+shift+e

Workspace And Surface Lanes

Workspaces and surfaces on distinct number and bracket lanes.

"$CMUX_SETTINGS" set shortcuts.bindings.selectWorkspaceByNumber cmd+1
"$CMUX_SETTINGS" set shortcuts.bindings.selectSurfaceByNumber cmd+opt+1
"$CMUX_SETTINGS" set shortcuts.bindings.nextSidebarTab 'cmd+opt+]'
"$CMUX_SETTINGS" set shortcuts.bindings.prevSidebarTab 'cmd+opt+['
"$CMUX_SETTINGS" set shortcuts.bindings.nextSurface 'cmd+shift+]'
"$CMUX_SETTINGS" set shortcuts.bindings.prevSurface 'cmd+shift+['

Browser-Style Terminal Navigation

For people who drive the terminal like a browser text field. Ctrl+W closes the surface at the shell prompt and still reaches vim, less, or tmux, because terminalAlternateScreen is true only while a full-screen app has the terminal. terminalFocus keeps Ctrl+W from closing a browser or sidebar surface, where terminalAlternateScreen reads false. Word and line motion come from two terminal settings rather than bindings.

"$CMUX_SETTINGS" set shortcuts.bindings.closeTab ctrl+w
"$CMUX_SETTINGS" set shortcuts.when.closeTab '"terminalFocus && !terminalAlternateScreen"'
"$CMUX_SETTINGS" set terminal.textEditingGestures true
"$CMUX_SETTINGS" set terminal.textEditingCommandMovesByWord true

With both terminal settings on, Command and Option arrows move by word, Command and Option Delete delete by word, and Control+Left/Right move to line start and end. Warn that macOS reserves Control+Left/Right for switching Spaces until they are turned off in System Settings > Keyboard > Keyboard Shortcuts > Mission Control, that Ctrl+W no longer deletes a word at the prompt (Option+Delete still does), and that Cmd+Tab belongs to the macOS app switcher and cannot be rebound in cmux. Also warn that textEditingCommandMovesByWord gives up the line kill: Cmd+Delete becomes the word kill (Ctrl+W) and nothing is left bound to Ctrl+U, so set terminal.textEditingCommandMovesByWord false is the layout to use if deleting to the start of the line matters more than deleting by word. If the user works inside tmux, add "$CMUX_SETTINGS" set terminal.textEditingGesturesInFullScreenApps true, because tmux keeps the terminal on the alternate screen and gestures otherwise pass through; !terminalAlternateScreen likewise reads tmux as a full-screen app, so Ctrl+W reaches tmux instead of closing the surface.

Browser Defaults Restore

Return embedded-browser behavior to common macOS browser shortcuts. unset keeps future cmux defaults applying.

for a in openBrowser focusBrowserAddressBar browserBack browserForward browserReload \
         browserZoomIn browserZoomOut browserZoomReset toggleBrowserDeveloperTools \
         showBrowserJavaScriptConsole find findNext findPrevious; do
  "$CMUX_SETTINGS" unset "shortcuts.bindings.$a"
done

Terminal-First Cleanup

Fewer app-level shortcuts. Prefer unbinding only the actions the user names; this is a starting proposal.

for a in renameTab renameWorkspace editWorkspaceDescription triggerFlash sendFeedback; do
  "$CMUX_SETTINGS" set "shortcuts.bindings.$a" null
done

Rules

• Do not edit ~/.config/cmux/settings.json unless the user explicitly asks; it is legacy fallback config.
• Do not overwrite all of shortcuts.bindings unless the user wants a full replacement.
• Do not invent action IDs. Validate against the schema or shortcut-actions.md.
• Do not apply a broad template without showing the changed actions first, unless the user named that template.
• Do not promise conflict detection from cmux-settings validate. It validates JSON and supported keys, not shortcut syntax, macOS reservation, or focus-context conflicts.
• 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.
• 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.