cmux-settings

cmux-settings

cmux reads user settings from ~/.config/cmux/cmux.json (JSONC). A file watcher applies changes on save, no restart. Legacy ~/.config/cmux/settings.json is read only as a fallback for keys absent from cmux.json.

Schema: https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json. The helper uses the schema-generated path list in references/all-keys.md in both checkouts and installed skills. If that reference is unavailable, it falls back to paths discoverable in Sources/CmuxSettingsJSONPathSupport.swift. Settings sections are app, terminal, notifications, sidebar, sidebarAppearance, workspaceColors, automation, agentMessages, browser, markdown, fileEditor, fileExplorer, diffViewer, and shortcuts. Non-settings sections (actions, ui, commands, vault, rightSidebar) share the same file.

For a viewer-specific route, read the viewer matrix. It distinguishes settings-backed knobs from structural configuration and viewer types that do not have a shipped setting yet. Do not invent a templates.<viewer> path: the schema is authoritative, and the adjacent templates proposal is not a supported configuration surface until its keys appear in web/data/cmux.schema.json.

Helper script

Use the bundled helper for every read/write. It strips JSONC comments, validates the complete proposed document with cmux config validate before writing, and writes atomically unless the change adds a validation issue. Issues the file already had, such as a key from a newer cmux, don't block an unrelated change; run validate to see them.

skills/cmux-settings/scripts/cmux-settings <subcommand>            # from a cmux checkout
~/.codex/skills/cmux-settings/scripts/cmux-settings <subcommand>   # installed Codex skill

The rest of this doc assumes it is on $PATH as cmux-settings; from a checkout, export PATH="$PWD/skills/cmux-settings/scripts:$PATH".

--file <path> overrides the target file. Scope is inferred from the real global paths and the project config discovered from the current directory; use --scope global|project to override that inference for an arbitrary file.

The installed cmux CLI covers the common edits without the helper: cmux config get|set|unset|toggle|cycle <path> and cmux config preset <name> validate against the same schema, keep comments, and write ~/.config/cmux/cmux.json. They share one write path with "type": "setting" and "type": "settingPreset" actions, which put the same edits on a tab bar button, shortcut, or Command Palette entry. Use the helper when you need --preview, receipts, undo, or a file other than the global config. Paths split on every ., so a key that itself contains . (for example a workspaceGroups.byCwd entry for ~/src/app.web) is refused by these commands with an error saying so; edit that key in the file directly.

Workflow

1. Look up the key when the user named a setting in plain English:

   cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'

1. Set it. JSON literals must be valid JSON.

   cmux-settings set sidebarAppearance.matchTerminalBackground true
   cmux-settings set app.appearance dark
   cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'
   cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'

1. Read back and cmux-settings validate.
2. Tell the user it auto-reloaded, and that cmux-settings unset <key> reverts it.

Viewer settings

Use the matrix to identify the surface before editing. The shipped settings-backed viewer paths are:

cmux-settings list-supported | rg '^(browser|markdown|fileEditor|fileExplorer|diffViewer)\.'

Examples:

cmux-settings set markdown.fontSize 16
cmux-settings set fileEditor.wordWrap true
cmux-settings set fileExplorer.doubleClickAction '"preferredEditor"'
cmux-settings set diffViewer.defaultLayout '"split"'

Browser profile import, per-page navigation, developer tools, and the current right-sidebar tab are runtime or UI state; use the browser/sidebar commands or the relevant Settings pane instead of adding guessed JSON keys. After any successful edit, run cmux reload-config and validate the exact path.

set and unset print a JSON result such as {"status": "persisted", "key": "app.appearance", "runtime": "unobserved"}. It records what reached disk; the running app's reload is not observed. A refusal prints {"status": "conflict", "code": ...} on stderr and exits 1 without writing. An invalid_config refusal adds issues, the path and message of each problem the change would add.

Reversible changes

Use these when a change may need to be taken back later, for example a preset the user can uninstall:

cmux-settings set computerUse.showInMenuBar false --preview        # prints the change and a revision; writes nothing
cmux-settings set computerUse.showInMenuBar false \
  --expect-revision <revision> --receipt ~/private/menu-bar-undo.json
cmux-settings undo ~/private/menu-bar-undo.json

• --expect-revision refuses the write if the file changed since the preview.
• --receipt creates a new mode-0600 file and never overwrites one; an existing file returns receipt_exists, and a path that can't be created returns receipt_unwritable, before anything is written. It holds config values, so keep it private.
• undo restores the prior value, or the prior absence, only while the path on the same resolved file still holds the value the receipt installed. If the user or another tool changed it since, undo returns undo_conflict and leaves the newer choice alone.
• Plain unset is an unconditional reset, not an undo.

Quick reference

• Appearance: app.appearance ("system" | "light" | "dark"), app.appIcon, app.menuBarOnly, app.minimalMode.
• Sidebar tint: sidebarAppearance.matchTerminalBackground, .tintColor, .tintOpacity (0..1).
• Sidebar details: sidebar.hideAllDetails, .showBranchDirectory, .showPullRequests, .showPorts, .showLog.
• Notifications: notifications.dockBadge, .sound (enum including "none", "custom_file"), .customSoundFilePath, .hooks (array).
• Browser: browser.defaultSearchEngine, .theme, .defaultZoomLevel, .openTerminalLinksInCmuxBrowser, .hostsToOpenInEmbeddedBrowser.
• Automation: automation.socketControlMode (off | cmuxOnly | automation | password | allowAll), .portBase, .portRange.
• Shortcuts: shortcuts.bindings.<actionId> = "cmd+b", ["ctrl+b","c"], null, or "" to unbind. Action ids in references/shortcut-actions.md.

Full list of settings, defaults, and descriptions: cmux-settings list-supported or references/all-keys.md.

Rules

• Only edit cmux.json. Never settings.json unless the user explicitly asks; it is legacy and read only when a key is absent from cmux.json.
• Never tell the user to restart cmux. The file watcher reloads on save.
• Always cmux-settings validate after a bulk edit. Validation errors include the exact config path and violated constraint.
• Do not blindly overwrite actions, ui, commands, vault, or rightSidebar; they share the file and hold hand-tuned non-settings config.
• Shortcut action ids must match the schema enum. Look them up before binding.
• Colors are #RRGGBB; opacities are 0..1.
• Translate app-level phrasing ("Settings > Notifications > Dock badge") to the JSON path first; web/app/[locale]/(landing)/docs/configuration/page.tsx mirrors the schema 1:1.