Keybinds

Two keymaps, not one

cmux splits shortcut ownership cleanly, and knowing which side owns a key saves a lot of hunting.

cmux shortcuts        # open Settings at Keyboard Shortcuts
cmux settings shortcuts

Holding ⌘ or ⌃ shows hint chips over the UI, controlled by shortcuts.showModifierHoldHints.

App and window

Workspaces

Surfaces and splits

Focus previous and next pane exist as actions but ship unbound. A Ghostty goto_split:previous keybind also cycles panes.

Browser, find, notifications, terminal

Mark all notifications read and clear all notifications are actions with no default binding. Browser devtools shortcuts follow Safari defaults.

Rebinding in cmux.json

shortcuts.bindings is keyed by cmux action id. A string is a single stroke, a two-element array is a chord, and several spellings unbind.

{
  "shortcuts": {
    "showModifierHoldHints": true,
    "bindings": {
      "splitRight": "cmd+shift+e",
      "splitDown": "ctrl+shift+o",
      "toggleSidebar": ["ctrl+b", "s"],
      "commandPalettePrevious": "none",
      "globalSearch": null
    }
  }
}

- Modifiers: cmd, command, shift, opt, option, alt, ctrl, control, ctl, or the glyphs ⌘ ⇧ ⌥ ⌃, joined with +. - The first stroke must include a modifier, except for Space. - Keys accept letters, digits, punctuation, f1–f20, arrows by name or glyph, tab, return, enter, space, and media keys. - Unbind with null, "", none, clear, unbound, or disabled. - A chord is at most two strokes, for example ["ctrl+b", "c"].

Action ids come from the schema, which is worth fetching for completion in an editor:

curl -fsSL https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json \
  -o ~/.config/cmux/cmux.schema.json

Scoping a binding with when

shortcuts.when takes VS Code style predicates keyed by the same action ids, so one key can behave differently depending on focus.

{
  "shortcuts": {
    "when": {
      "selectWorkspaceByNumber": "!sidebarFocus",
      "selectSurfaceByNumber": "sidebarMode == 'find' && paneCount > 1"
    }
  }
}

Boolean context keys: sidebarFocus, browserFocus, markdownFocus, filePreviewTextEditorFocus, simulatorFocus, terminalFocus, commandPaletteVisible, terminalFindVisible, workspaceCanvasLayout. Typed keys: the string sidebarMode (files, find, sessions, feed, dock) and the integers paneCount and workspaceCount. Operators are ==, !=, =~, <, <=, >, >=, and in [a, b], combined with !, &&, ||, and parentheses. An unknown or absent key reads as false, and the shortcut only fires, and only conflicts with other shortcuts, while the clause holds.

Run cmux reload-config after editing, no restart needed.