Document Location
This document lives in github.com/vtmocanu/skills at cmux-settings/SKILL.md.
Note: This is the source of truth. Generated copies in your agent's skills directory (e.g. Claude Code's ~/.claude/commands/) are derived from this file via dot-ai skills generate --repo https://github.com/vtmocanu/skills. Edit here and regenerate; never edit generated copies. Upstream source: manaflow-ai/cmux (skills/cmux-settings/); re-sync from upstream rather than authoring from scratch.
cmux-settings
cmux reads user settings from ~/.config/cmux/cmux.json (JSONC). The app installs a file watcher; saving the file applies changes immediately, no restart needed. Legacy ~/.config/cmux/settings.json is read only as a fallback for keys not present in cmux.json.
Schema: https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json. The authoritative path list lives in Sources/CmuxSettingsJSONPathSupport.swift in the cmux checkout, and the installed skill includes a generated copy in references/all-keys.md. Top-level sections are app, terminal, notifications, sidebar, sidebarAppearance, workspaceColors, automation, browser, and shortcuts. Non-settings sections (actions, ui, commands, vault, rightSidebar) coexist in the same file.
Helper script
Use the bundled helper for every read/write. It strips JSONC comments, writes atomically, and validates keys against the schema.
# Bundled with this skill (the dot-ai generator rewrites ./scripts to the absolute install path)
./scripts/cmux-settings <subcommand>
For brevity in the rest of this doc, assume the script is on $PATH as cmux-settings.
Subcommands:
| Command |
What it does |
cmux-settings path |
Print the config path. |
cmux-settings dump |
Print the raw file (preserves comments). |
cmux-settings dump --no-comments |
Print the parsed JSON. |
cmux-settings get <a.b.c> |
Print value at dotted JSON path. |
cmux-settings set <a.b.c> <value> |
Set value. <value> is parsed as JSON (true, 42, "text", […], {…}); plain strings without quotes are 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 any unknown settings keys. |
cmux-settings open |
Open cmux.json in $EDITOR, VS Code, Cursor, or TextEdit. |
--file <path> overrides the target file (useful for --file ~/.config/cmux/settings.json when the user keeps things in the legacy file).
Workflow
- Confirm the change. If the user named a setting in plain English (e.g. "make the sidebar tint match the terminal background"), look it up first.
cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'
- Set the value. JSON literals (
true, false, numbers, arrays, objects) must be valid JSON. Plain words are stored as strings.cmux-settings set sidebarAppearance.matchTerminalBackground true
cmux-settings set app.appearance dark
cmux-settings set shortcuts.bindings.toggleSidebar cmd+b
cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'
cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'
- Verify by reading back and validating.
cmux-settings get sidebarAppearance.matchTerminalBackground
cmux-settings validate
- Tell the user it auto-reloaded. No app restart. If they want to revert, run
cmux-settings unset <key>.
Quick reference
- Appearance:
app.appearance = "system" | "light" | "dark", app.appIcon, app.menuBarOnly, app.minimalMode.
- Sidebar tint:
sidebarAppearance.matchTerminalBackground, sidebarAppearance.tintColor, sidebarAppearance.tintOpacity (0..1).
- Sidebar details:
sidebar.hideAllDetails, sidebar.showBranchDirectory, sidebar.showPullRequests, sidebar.showPorts, sidebar.showLog.
- Notifications:
notifications.dockBadge, notifications.sound (enum incl. "none", "custom_file"), notifications.customSoundFilePath, notifications.hooks (array).
- Browser:
browser.defaultSearchEngine, browser.theme, browser.openTerminalLinksInCmuxBrowser, browser.hostsToOpenInEmbeddedBrowser.
- Automation:
automation.socketControlMode (off | cmuxOnly | automation | password | allowAll), automation.portBase, automation.portRange.
- Shortcuts:
shortcuts.bindings.<actionId> = "cmd+b", ["ctrl+b","c"], null, or "" to unbind. See references/shortcut-actions.md.
For the full list of settings, defaults, and descriptions, run cmux-settings list-supported or read references/all-keys.md.
Rules
- Only edit
cmux.json. Never edit settings.json unless the user explicitly asks; it is legacy and only read when the key is absent from cmux.json.
- Never tell the user to restart cmux to apply a change. The file watcher reloads on save.
- Always validate after a bulk edit:
cmux-settings validate. Unknown keys mean the user pasted a key the app does not consume.
- Do not blindly overwrite top-level sections (
actions, ui, commands, vault, rightSidebar). They live in the same file and contain non-settings config the user has hand-tuned.
- Shortcut action ids must match the schema enum. Look them up in references/shortcut-actions.md before binding.
- Color values must be
#RRGGBB. Opacities are 0..1.
- For settings the user expressed in app-level language (e.g. "Settings > Notifications > Dock badge"), translate to the matching JSON path first; the docs page at
web/app/[locale]/docs/configuration/page.tsx mirrors the schema 1:1.
1---2name: cmux-settings3description: View and edit cmux settings in ~/.config/cmux/cmux.json. Use when the user wants to change cmux preferences (appearance, sidebar, notifications, automation, browser, shortcuts), set a value by JSON path, validate the file, open it in an editor, or look up which keys cmux recognizes. Triggers on '/cmux-settings', 'change cmux setting', 'set a value in cmux', 'cmux config', 'cmux.json', or 'rebind a cmux shortcut'.4---56## Document Location7This document lives in [github.com/vtmocanu/skills](https://github.com/vtmocanu/skills) at `cmux-settings/SKILL.md`.89> **Note**: This is the source of truth. Generated copies in your agent's skills directory (e.g. Claude Code's `~/.claude/commands/`) are derived from this file via `dot-ai skills generate --repo https://github.com/vtmocanu/skills`. Edit here and regenerate; never edit generated copies. Upstream source: `manaflow-ai/cmux` (skills/cmux-settings/); re-sync from upstream rather than authoring from scratch.1011# cmux-settings1213cmux reads user settings from `~/.config/cmux/cmux.json` (JSONC). The app installs a file watcher; saving the file applies changes immediately, no restart needed. Legacy `~/.config/cmux/settings.json` is read only as a fallback for keys not present in `cmux.json`.1415Schema: `https://raw.githubusercontent.com/manaflow-ai/cmux/main/web/data/cmux.schema.json`. The authoritative path list lives in `Sources/CmuxSettingsJSONPathSupport.swift` in the cmux checkout, and the installed skill includes a generated copy in `references/all-keys.md`. Top-level sections are `app`, `terminal`, `notifications`, `sidebar`, `sidebarAppearance`, `workspaceColors`, `automation`, `browser`, and `shortcuts`. Non-settings sections (`actions`, `ui`, `commands`, `vault`, `rightSidebar`) coexist in the same file.1617## Helper script1819Use the bundled helper for every read/write. It strips JSONC comments, writes atomically, and validates keys against the schema.2021```bash22# Bundled with this skill (the dot-ai generator rewrites ./scripts to the absolute install path)23./scripts/cmux-settings <subcommand>24```2526For brevity in the rest of this doc, assume the script is on `$PATH` as `cmux-settings`.2728Subcommands:2930| Command | What it does |31|---|---|32| `cmux-settings path` | Print the config path. |33| `cmux-settings dump` | Print the raw file (preserves comments). |34| `cmux-settings dump --no-comments` | Print the parsed JSON. |35| `cmux-settings get <a.b.c>` | Print value at dotted JSON path. |36| `cmux-settings set <a.b.c> <value>` | Set value. `<value>` is parsed as JSON (`true`, `42`, `"text"`, `[…]`, `{…}`); plain strings without quotes are stored as strings. |37| `cmux-settings unset <a.b.c>` | Delete key, reverting to the in-app default. |38| `cmux-settings list-supported` | List every settings JSON path the app recognizes. |39| `cmux-settings validate` | Parse the file and flag any unknown settings keys. |40| `cmux-settings open` | Open `cmux.json` in `$EDITOR`, VS Code, Cursor, or TextEdit. |4142`--file <path>` overrides the target file (useful for `--file ~/.config/cmux/settings.json` when the user keeps things in the legacy file).4344## Workflow45461. Confirm the change. If the user named a setting in plain English (e.g. "make the sidebar tint match the terminal background"), look it up first.47 ```bash48 cmux-settings list-supported | rg -i 'sidebar.*terminal|terminal.*sidebar'49 ```502. Set the value. JSON literals (`true`, `false`, numbers, arrays, objects) must be valid JSON. Plain words are stored as strings.51 ```bash52 cmux-settings set sidebarAppearance.matchTerminalBackground true53 cmux-settings set app.appearance dark54 cmux-settings set shortcuts.bindings.toggleSidebar cmd+b55 cmux-settings set shortcuts.bindings.newTab '["ctrl+b","c"]'56 cmux-settings set browser.hostsToOpenInEmbeddedBrowser '["localhost","*.internal.example"]'57 ```583. Verify by reading back and validating.59 ```bash60 cmux-settings get sidebarAppearance.matchTerminalBackground61 cmux-settings validate62 ```634. Tell the user it auto-reloaded. No app restart. If they want to revert, run `cmux-settings unset <key>`.6465## Quick reference6667- Appearance: `app.appearance` = `"system" | "light" | "dark"`, `app.appIcon`, `app.menuBarOnly`, `app.minimalMode`.68- Sidebar tint: `sidebarAppearance.matchTerminalBackground`, `sidebarAppearance.tintColor`, `sidebarAppearance.tintOpacity` (0..1).69- Sidebar details: `sidebar.hideAllDetails`, `sidebar.showBranchDirectory`, `sidebar.showPullRequests`, `sidebar.showPorts`, `sidebar.showLog`.70- Notifications: `notifications.dockBadge`, `notifications.sound` (enum incl. `"none"`, `"custom_file"`), `notifications.customSoundFilePath`, `notifications.hooks` (array).71- Browser: `browser.defaultSearchEngine`, `browser.theme`, `browser.openTerminalLinksInCmuxBrowser`, `browser.hostsToOpenInEmbeddedBrowser`.72- Automation: `automation.socketControlMode` (`off | cmuxOnly | automation | password | allowAll`), `automation.portBase`, `automation.portRange`.73- Shortcuts: `shortcuts.bindings.<actionId>` = `"cmd+b"`, `["ctrl+b","c"]`, `null`, or `""` to unbind. See `references/shortcut-actions.md`.7475For the full list of settings, defaults, and descriptions, run `cmux-settings list-supported` or read [references/all-keys.md](references/all-keys.md).7677## Rules7879- Only edit `cmux.json`. Never edit `settings.json` unless the user explicitly asks; it is legacy and only read when the key is absent from `cmux.json`.80- Never tell the user to restart cmux to apply a change. The file watcher reloads on save.81- Always validate after a bulk edit: `cmux-settings validate`. Unknown keys mean the user pasted a key the app does not consume.82- Do not blindly overwrite top-level sections (`actions`, `ui`, `commands`, `vault`, `rightSidebar`). They live in the same file and contain non-settings config the user has hand-tuned.83- Shortcut action ids must match the schema enum. Look them up in [references/shortcut-actions.md](references/shortcut-actions.md) before binding.84- Color values must be `#RRGGBB`. Opacities are `0..1`.85- For settings the user expressed in app-level language (e.g. "Settings > Notifications > Dock badge"), translate to the matching JSON path first; the docs page at `web/app/[locale]/docs/configuration/page.tsx` mirrors the schema 1:1.
vtmocanu