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, browser, shortcuts. Non-settings sections (actions, ui, commands, vault, rightSidebar) share the same file.

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 only after semantic validation passes.

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.

Workflow

1. Look up the key when the user named a setting in plain English: ``bash cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar' ``
2. Set it. JSON literals must be valid JSON. ``bash 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"]' ``
3. Read back and cmux-settings validate.
4. Tell the user it auto-reloaded, and that cmux-settings unset <key> reverts it.

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.