Cmux Config

cmux-config

Single entry point for editing a user's cmux configuration in ~/.config/cmux/cmux.json (JSONC). The app watches the file; saving applies changes immediately, no restart. Legacy ~/.config/cmux/settings.json is read only as a fallback for keys absent from cmux.json.

Three areas, each with a reference:

• Settings — typed preferences under app, terminal, notifications,

sidebar, sidebarAppearance, workspaceColors, automation, browser, shortcuts. See the helper below and references/all-keys.md / references/shortcut-actions.md.

• Customization — structural config: actions, ui.surfaceTabBar.buttons,

ui.newWorkspace (plus-button click + context menu), commands, rightSidebar, vault. See references/customize.md.

• Workspace groups — collapsible anchor-owned sidebar sections via the `cmux

workspace group CLI / socket API and workspaceGroups` config. See references/groups.md.

Helper script

Use the bundled helper for every settings/customize read and write. It strips JSONC comments, writes atomically, and validates keys against the schema. From the installed skill directory:

./scripts/cmux-settings <subcommand>

For brevity below, assume it is on $PATH as cmux-settings (e.g. export PATH="$HOME/.claude/skills/cmux-config/scripts:$PATH").

--file <path> overrides the target file (use for the legacy settings.json).

Schema: https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json.

Workflow

1. If the user named a setting in plain English, look it up first: cmux-settings list-supported | rg -i '<keywords>'. 2. Make the smallest edit (settings/customize via the helper; groups via the cmux workspace group CLI in references/groups.md). 3. Verify by surface:

• Typed settings: read back (cmux-settings get <path>) and cmux-settings validate.
• Customization (actions, ui.*, commands, vault, rightSidebar): read back the

exact key (cmux-settings get <path>) and confirm the file still parses (cmux-settings dump --no-comments). Do NOT rely on validate here: it skips structural sections, so a typo like ui.surfaceTabbar.buttons passes validation yet cmux ignores it. Check the key against references/customize.md.

• Groups: cmux workspace group list (the settings validator does not recognize

workspaceGroups). 4. Tell the user it auto-reloaded on save. No app restart. Revert with cmux-settings unset <key>.

Rules

• Only edit cmux.json. Never edit settings.json unless asked; it is legacy.
• Never tell the user to restart cmux to apply a change; the watcher reloads on save.
• Do not blindly overwrite top-level structural sections (actions, ui,

commands, vault, rightSidebar); they hold hand-tuned non-settings config.

• Color values are #RRGGBB; opacities are 0..1.
• Shortcut action ids must match the schema enum; look them up in

references/shortcut-actions.md before binding.

• Do not run a tagged app reload for config-only or skill-only changes.
• For workspace groups prefer CLI/socket operations over editing session JSON, and

preserve anchor semantics (see references/groups.md).

All settings keys

Auto-generated from repo/web/data/cmux.schema.json. For the rendered docs, see https://cmux.dev/docs/configuration.

app

General app preferences from Settings > App.

terminal

Terminal presentation settings from Settings > Terminal.

notifications

Notification behavior from Settings > Notifications.

sidebar

Sidebar content and metadata visibility from Settings > Sidebar.

workspaceColors

Workspace tab and badge colors from Settings > Workspace Colors.

sidebarAppearance

Sidebar tint settings from Settings > Sidebar Appearance.

automation

Socket control and automation settings from Settings > Automation.

browser

Embedded browser settings from Settings > Browser.

shortcuts

Keyboard shortcut settings from Settings > Keyboard Shortcuts.

cmux Customization (cmux-config reference)

Personal cmux configuration changes stored outside the app source tree, especially ~/.config/cmux/cmux.json and project-local .cmux/cmux.json files. Covers action registry entries, surface tab bar buttons, plus-button click and right-click menu behavior, custom workspace commands, right sidebar wiring, and related config cleanup.

Prerequisites

• Use this skill's cmux-settings helper script (scripts/cmux-settings) for global ~/.config/cmux/cmux.json reads and writes.
• For standard typed settings under app, terminal, notifications, sidebar, sidebarAppearance, workspaceColors, automation, browser, or shortcuts, see the Settings section of cmux-config SKILL.md and references/all-keys.md.

Reference

Global config:

cmux-settings path
cmux-settings dump --no-comments

Common structural sections in cmux.json:

• actions: action registry used by custom UI and commands.
• ui.surfaceTabBar.buttons: buttons shown in the surface tab bar.
• ui.newWorkspace.action: action triggered by a normal click on the plus button.
• ui.newWorkspace.contextMenu: menu items shown when right-clicking the plus button.
• commands: named workspace commands and layouts.
• rightSidebar: custom right sidebar wiring.
• vault: custom Vault agent registrations.

ui.surfaceTabBar.buttons can contain built-in action ids as strings or object references:

[
  "cmux.newTerminal",
  "cmux.newBrowser",
  "cmux.splitRight",
  "cmux.splitDown",
  { "action": "custom-action-id" }
]

Use ui.newWorkspace.contextMenu for plus-button right-click menus. ui.newWorkspace.rightClick is accepted by cmux as a legacy alias, but new edits should use contextMenu.

Workflow

Step 1: Inspect current config

Read the existing config before changing anything.

cmux-settings dump --no-comments

If the user names a visible UI surface, search for the related ids.

rg -n "surfaceTabBar|newWorkspace|rightSidebar|<action-id>|<label>" ~/.config/cmux/cmux.json

Step 2: Make the smallest config edit

Use the helper for global config edits. It parses JSONC and writes atomically.

Remove custom agent launch buttons from the surface tab bar while keeping built-in surface controls:

cmux-settings set ui.surfaceTabBar.buttons \
  '["cmux.newTerminal","cmux.newBrowser","cmux.splitRight","cmux.splitDown"]'

Remove one named action from a tab bar without deleting the action registry entry:

cmux-settings get ui.surfaceTabBar.buttons
# Edit the array to remove only { "action": "<action-id>" }, then set it back.

Delete an action entirely only when the user asks for the command itself to go away from every surface.

cmux-settings unset actions.<action-id>

Customize the plus button and its right-click menu:

cmux-settings set ui.newWorkspace.action '"workspace-new-cmux-worktree"'
cmux-settings set ui.newWorkspace.contextMenu \
  '[{"action":"workspace-new-cmux-worktree","title":"New cmux Worktree"},{"action":"workspace-terminal-browser","title":"Terminal + Browser"},{"type":"separator"},{"action":"cmux.newTerminal","title":"New Terminal"},{"action":"cmux.newBrowser","title":"New Browser"}]'

Step 3: Verify

Always read back the changed path.

cmux-settings get ui.surfaceTabBar.buttons
cmux-settings get ui.newWorkspace.contextMenu

Validate parseability. The strict supported-key validator may flag valid structural or newer app keys when the checked-out source list is older than the running app. If that happens, do not remove unrelated keys. Confirm the file parses and report the unrelated validator warning.

cmux-settings dump --no-comments >/tmp/cmux-config.json

Step 4: Report apply behavior

cmux watches ~/.config/cmux/cmux.json, so config edits apply after save without a rebuild. Do not run a tagged app reload for pure config or skill changes.

Rules

• Preserve unrelated custom actions, commands, menus, Vault entries, and right sidebar config.
• Do not delete action definitions just because their buttons were removed from the tab bar.
• Do not use defaults write for persistent product config.
• Do not edit repo/ for user config changes.
• Do not run app reloads for config-only or skill-only changes.
• Keep responses short and include the exact path or key changed.

cmux workspace groups (cmux-config reference)

Workspace groups are collapsible named sections in the cmux sidebar. Each group is owned by an anchor workspace. The group header is the anchor's sidebar representation, so there is no separate row for the anchor. Closing the anchor dissolves the group while preserving the other members as ungrouped workspaces.

CLI

Prefer the canonical noun form:

cmux workspace group list [--json]
cmux workspace group create --name <name> [--cwd <path>] [--from <id>,<id>]
cmux workspace group ungroup <group-id>
cmux workspace group delete <group-id>
cmux workspace group rename <group-id> --name <new>
cmux workspace group collapse <group-id>
cmux workspace group expand <group-id>
cmux workspace group pin <group-id>
cmux workspace group unpin <group-id>
cmux workspace group add --group <group-id> --workspace <workspace-id>
cmux workspace group remove --workspace <workspace-id>
cmux workspace group set-anchor --group <group-id> --workspace <workspace-id>
cmux workspace group new-workspace <group-id> [--placement afterCurrent|top|end]
cmux workspace group set-color <group-id> [--hex #RRGGBB]
cmux workspace group set-icon <group-id> [--symbol <sf-symbol>]
cmux workspace group move <group-id> --to-index <n> | --before <group-id> | --after <group-id>
cmux workspace group focus <group-id>

cmux workspace-group ... is a compatibility alias for the same operations. <group-id> accepts UUIDs or refs such as workspace_group:1. All commands honor --json.

create inserts a fresh anchor workspace. It does not promote an existing workspace into the anchor. --from lists workspaces that become children under the new anchor. When --from is omitted, cmux uses the active sidebar selection or caller workspace when available.

ungroup dissolves a group while keeping every member workspace alive, including the anchor, which becomes a regular ungrouped workspace. delete is destructive and closes every workspace in the group.

new-workspace runs the group's new-workspace behavior: a new workspace is created at the anchor cwd and joined to the group. Placement can be passed explicitly, resolved from per-cwd config, or resolved from the global group default.

Socket methods

The CLI is a thin wrapper over the v2 JSON socket API. Anything callable via CLI is also callable directly:

workspace.group.list
workspace.group.create        { name, cwd?, child_workspace_ids? }
workspace.group.ungroup       { group_id }
workspace.group.delete        { group_id }
workspace.group.rename        { group_id, name }
workspace.group.collapse      { group_id }
workspace.group.expand        { group_id }
workspace.group.pin           { group_id }
workspace.group.unpin         { group_id }
workspace.group.add           { group_id, workspace_id }
workspace.group.remove        { workspace_id }
workspace.group.set_anchor    { group_id, workspace_id }
workspace.group.new_workspace { group_id, placement? }
workspace.group.set_color     { group_id, hex? }
workspace.group.set_icon      { group_id, symbol? }
workspace.group.move          { group_id, to_index? | before_group_id? | after_group_id? }
workspace.group.focus         { group_id }

All accept the standard window_id / window_ref parameter to target a non-focused window.

Configuration (~/.config/cmux/cmux.json)

Per-group settings are keyed by the anchor cwd. Keys with * or ? are fnmatch globs with ~ expansion. Other keys are path prefixes. Longest match wins.

{
  "workspaceGroups": {
    "newWorkspacePlacement": "afterCurrent",
    "byCwd": {
      "/abs/path/to/repo": {
        "color": "#7A4FD8",
        "icon": "ladybug.fill",
        "newWorkspacePlacement": "top",
        "contextMenu": [
          { "action": "newWorktreeAction", "title": "New Worktree" },
          { "action": "newWorkspace" }
        ]
      },
      "~/projects/*": {
        "icon": "leaf.fill",
        "newWorkspacePlacement": "end"
      }
    }
  }
}

workspaceGroups.newWorkspacePlacement and workspaceGroups.byCwd[...].newWorkspacePlacement accept:

• afterCurrent: after the active in-group workspace. It falls back to top when there is no active member reference.
• top: second slot, right after the anchor.
• end: after the last member.

Resolution order for group new-workspace placement:

1. Explicit --placement afterCurrent|top|end on the CLI, or "placement" in workspace.group.new_workspace. 2. Per-cwd workspaceGroups.byCwd[...].newWorkspacePlacement. 3. Global workspaceGroups.newWorkspacePlacement. 4. Built-in default afterCurrent.

Cmd-N inside a group uses the active group workspace as the placement reference. The group header + button and CLI path use the anchor as the reference, so afterCurrent behaves like top there.

Group context-menu items use the same schema as ui.newWorkspace.contextMenu; actions must be defined in the global actions block or be built-in actions such as newWorkspace.

Keyboard

Default shortcut: Cmd-Shift-G groups the sidebar-selected workspaces. It falls back to the focused workspace when no sidebar selection exists. Rebind it in Settings > Keyboard.

Anchor semantics

• Anchor identity lives on the group (anchorWorkspaceId), not as a flag on the workspace.
• The anchor renders as the group header, with no separate sidebar row.
• Closing the anchor dissolves the group after a confirm dialog.
• set-anchor reassigns which member is the anchor; the previously-anchor workspace becomes a regular member with its own sidebar row.

Persistence

Groups and membership round-trip through ~/Library/Application Support/cmux/session-<bundle-id>.json via the existing SessionPersistenceStore. Atomic rename-into-place writes; no WAL.

Rules

• Prefer CLI or socket operations over editing session JSON.
• Do not write unsupported future config keys. Check web/data/cmux.schema.json in cmux when unsure.
• Preserve anchor semantics when scripting: moving a group means moving the anchor section, not only a child workspace row.
• Use ungroup when workspaces should survive; use delete only when every workspace in the group should close.

Keyboard shortcut action ids

Auto-generated from repo/web/data/cmux.schema.json (shortcuts.bindings.propertyNames.enum). Regenerate by re-running the snippet inline in SKILL.md.

Values for shortcuts.bindings.<action>:

• A string like "cmd+b" for a single shortcut.
• A two-element array like ["ctrl+b","c"] for a chord.
• null or an empty string ("", "none", "clear", "unbound", "disabled") to unbind.

App

• shortcuts.bindings.openSettings
• shortcuts.bindings.reloadConfiguration
• shortcuts.bindings.showHideAllWindows
• shortcuts.bindings.globalSearch
• shortcuts.bindings.newWindow
• shortcuts.bindings.closeWindow
• shortcuts.bindings.toggleFullScreen
• shortcuts.bindings.quit
• shortcuts.bindings.openFolder
• shortcuts.bindings.sendFeedback

Tabs

• shortcuts.bindings.newTab
• shortcuts.bindings.reopenPreviousSession
• shortcuts.bindings.renameTab
• shortcuts.bindings.closeTab
• shortcuts.bindings.closeOtherTabsInPane

Workspace

• shortcuts.bindings.goToWorkspace
• shortcuts.bindings.selectWorkspaceByNumber
• shortcuts.bindings.renameWorkspace
• shortcuts.bindings.editWorkspaceDescription
• shortcuts.bindings.closeWorkspace

Panes and surfaces

• shortcuts.bindings.nextSurface
• shortcuts.bindings.prevSurface
• shortcuts.bindings.selectSurfaceByNumber
• shortcuts.bindings.newSurface
• shortcuts.bindings.toggleTerminalCopyMode
• shortcuts.bindings.focusLeft
• shortcuts.bindings.focusRight
• shortcuts.bindings.focusUp
• shortcuts.bindings.focusDown
• shortcuts.bindings.splitRight
• shortcuts.bindings.splitDown
• shortcuts.bindings.toggleSplitZoom
• shortcuts.bindings.equalizeSplits

Command palette

• shortcuts.bindings.commandPalette
• shortcuts.bindings.commandPaletteNext
• shortcuts.bindings.commandPalettePrevious

Notifications

• shortcuts.bindings.showNotifications
• shortcuts.bindings.jumpToUnread
• shortcuts.bindings.toggleUnread
• shortcuts.bindings.markOldestUnreadAndJumpNext
• shortcuts.bindings.triggerFlash

Right sidebar

• shortcuts.bindings.toggleSidebar
• shortcuts.bindings.focusRightSidebar
• shortcuts.bindings.switchRightSidebarToFiles
• shortcuts.bindings.switchRightSidebarToFind
• shortcuts.bindings.switchRightSidebarToSessions
• shortcuts.bindings.switchRightSidebarToFeed
• shortcuts.bindings.switchRightSidebarToDock
• shortcuts.bindings.nextSidebarTab
• shortcuts.bindings.prevSidebarTab

Browser

• shortcuts.bindings.reopenClosedBrowserPanel
• shortcuts.bindings.splitBrowserRight
• shortcuts.bindings.splitBrowserDown
• shortcuts.bindings.openBrowser
• shortcuts.bindings.focusBrowserAddressBar
• shortcuts.bindings.browserBack
• shortcuts.bindings.browserForward
• shortcuts.bindings.browserReload
• shortcuts.bindings.browserZoomIn
• shortcuts.bindings.browserZoomOut
• shortcuts.bindings.browserZoomReset
• shortcuts.bindings.toggleBrowserDeveloperTools
• shortcuts.bindings.showBrowserJavaScriptConsole

Find

• shortcuts.bindings.find
• shortcuts.bindings.findInDirectory
• shortcuts.bindings.findNext
• shortcuts.bindings.findPrevious
• shortcuts.bindings.hideFind
• shortcuts.bindings.useSelectionForFind

Files and React Grab

• shortcuts.bindings.toggleFileExplorer
• shortcuts.bindings.saveFilePreview
• shortcuts.bindings.toggleReactGrab