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
- If the user named a setting in plain English, look it up first:
cmux-settings list-supported | rg -i '<keywords>'.
- Make the smallest edit (settings/customize via the helper; groups via the
cmux workspace group CLI in references/groups.md).
- 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).
- 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).
1---2name: cmux-config3description: Configure cmux through ~/.config/cmux/cmux.json: settings (appearance, sidebar, notifications, automation, browser, shortcuts, set/get/validate by JSON path), customization (tab bar buttons, plus-button click and right-click menus, custom actions/commands/menus, right sidebar), and sidebar workspace groups (anchor workspaces, group CLI/socket ops, per-cwd group config). Triggers: 'cmux config', 'cmux.json', 'change cmux setting', 'set <x> in cmux', 'rebind a cmux shortcut', 'cmux-customize', 'customize cmux', 'tab bar button', 'add cmux action', 'workspace group', 'group sidebar', 'anchor workspace', 'workspaceGroups'.4---56# cmux-config78Single entry point for editing a user's cmux configuration in9`~/.config/cmux/cmux.json` (JSONC). The app watches the file; saving applies10changes immediately, no restart. Legacy `~/.config/cmux/settings.json` is read11only as a fallback for keys absent from `cmux.json`.1213Three areas, each with a reference:1415- **Settings** — typed preferences under `app`, `terminal`, `notifications`,16 `sidebar`, `sidebarAppearance`, `workspaceColors`, `automation`, `browser`,17 `shortcuts`. See the helper below and [references/all-keys.md](references/all-keys.md) /18 [references/shortcut-actions.md](references/shortcut-actions.md).19- **Customization** — structural config: `actions`, `ui.surfaceTabBar.buttons`,20 `ui.newWorkspace` (plus-button click + context menu), `commands`, `rightSidebar`,21 `vault`. See [references/customize.md](references/customize.md).22- **Workspace groups** — collapsible anchor-owned sidebar sections via the `cmux23 workspace group` CLI / socket API and `workspaceGroups` config. See24 [references/groups.md](references/groups.md).2526## Helper script2728Use the bundled helper for every settings/customize read and write. It strips29JSONC comments, writes atomically, and validates keys against the schema. From the30installed skill directory:3132```bash33./scripts/cmux-settings <subcommand>34```3536For brevity below, assume it is on `$PATH` as `cmux-settings` (e.g.37`export PATH="$HOME/.claude/skills/cmux-config/scripts:$PATH"`).3839| Command | What it does |40|---|---|41| `cmux-settings path` | Print the config path. |42| `cmux-settings dump [--no-comments]` | Print the raw file (or parsed JSON). |43| `cmux-settings get <a.b.c>` | Print value at dotted JSON path. |44| `cmux-settings set <a.b.c> <value>` | Set value (`<value>` parsed as JSON; bare words stored as strings). |45| `cmux-settings unset <a.b.c>` | Delete key, reverting to the in-app default. |46| `cmux-settings list-supported` | List every settings JSON path the app recognizes. |47| `cmux-settings validate` | Parse the file and flag unknown settings keys. |48| `cmux-settings open` | Open `cmux.json` in `$EDITOR` / VS Code / Cursor / TextEdit. |4950`--file <path>` overrides the target file (use for the legacy `settings.json`).5152Schema: `https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json`.5354## Workflow55561. If the user named a setting in plain English, look it up first:57 `cmux-settings list-supported | rg -i '<keywords>'`.582. Make the smallest edit (settings/customize via the helper; groups via the59 `cmux workspace group` CLI in [references/groups.md](references/groups.md)).603. Verify by surface:61 - **Typed settings:** read back (`cmux-settings get <path>`) and `cmux-settings validate`.62 - **Customization** (`actions`, `ui.*`, `commands`, `vault`, `rightSidebar`): read back the63 exact key (`cmux-settings get <path>`) and confirm the file still parses64 (`cmux-settings dump --no-comments`). Do NOT rely on `validate` here: it skips structural65 sections, so a typo like `ui.surfaceTabbar.buttons` passes validation yet cmux ignores it.66 Check the key against [references/customize.md](references/customize.md).67 - **Groups:** `cmux workspace group list` (the settings validator does not recognize68 `workspaceGroups`).694. Tell the user it auto-reloaded on save. No app restart. Revert with70 `cmux-settings unset <key>`.7172## Rules7374- Only edit `cmux.json`. Never edit `settings.json` unless asked; it is legacy.75- Never tell the user to restart cmux to apply a change; the watcher reloads on save.76- Do not blindly overwrite top-level structural sections (`actions`, `ui`,77 `commands`, `vault`, `rightSidebar`); they hold hand-tuned non-settings config.78- Color values are `#RRGGBB`; opacities are `0..1`.79- Shortcut action ids must match the schema enum; look them up in80 [references/shortcut-actions.md](references/shortcut-actions.md) before binding.81- Do not run a tagged app reload for config-only or skill-only changes.82- For workspace groups prefer CLI/socket operations over editing session JSON, and83 preserve anchor semantics (see [references/groups.md](references/groups.md)).
manaflow-ai