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").

Command	What it does
cmux-settings path	Print the config path.
cmux-settings dump [--no-comments]	Print the raw file (or parsed JSON).
cmux-settings get <a.b.c>	Print value at dotted JSON path.
cmux-settings set <a.b.c> <value>	Set value (<value> parsed as JSON; bare words stored as strings).
cmux-settings unset <a.b.c>	Delete key, reverting to the in-app default.
cmux-settings list-supported	List every settings JSON path the app recognizes.
cmux-settings validate	Parse the file and flag unknown settings keys.
cmux-settings open	Open cmux.json in $EDITOR / VS Code / Cursor / TextEdit.

--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).