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 . 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: 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 . 4. Apply only the chosen action paths, then "$CMUX SETTINGS" validate . 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. macOS Terminal/iTerm Restore These actions already match cmux built in defaults, so clear file overrides rather than writing default values. Vim Pane Navigation Prefix free pane movement with no arrow keys. 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 . Workspace And Surface Lanes Workspaces and surfaces on distinct number and bracket lanes. 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. 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. Terminal First Cleanup Fewer app level shortcuts. Prefer unbinding only the actions the user names; this is a starting proposal. 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.

cmux-keyboard-shortcuts