cmux-settings

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 <something> in cmux', 'cmux config', 'cmux.json', or 'rebind a cmux shortcut'.

22,779stars1,786forksUpdated 6/24/2026

Developer Tools #configuration #settings #json #cmux #keybindings

Security Assessment

Safe(100/100)

Security Score100/100

About cmux-settings

A configuration skill for viewing and editing cmux settings, which live in `~/.config/cmux/cmux.json` (JSONC). cmux installs a file watcher, so saving the file applies changes immediately without a restart; a legacy `~/.config/cmux/settings.json` is read only as a fallback for keys absent from `cmux.json`. It is meant for changing cmux preferences—appearance, sidebar, notifications, automation, browser, and shortcuts—setting a value by JSON path, validating the file, opening it in an editor, or looking up which keys cmux recognizes. Triggers include `/cmux-settings`, "change cmux setting", "cmux config", "cmux.json", and "rebind a cmux shortcut".

Settings are organized into top-level sections: `app`, `terminal`, `notifications`, `sidebar`, `sidebarAppearance`, `workspaceColors`, `automation`, `browser`, and `shortcuts`. Non-settings sections (`actions`, `ui`, `commands`, `vault`, `rightSidebar`) coexist in the same file and contain hand-tuned config that must not be blindly overwritten. The authoritative key list lives in `Sources/CmuxSettingsJSONPathSupport.swift`, with a generated copy in `references/all-keys.md` and a JSON schema published in the repository. Examples include automation keys such as `automation.socketControlMode` (off, cmuxOnly, automation, password, allowAll), `automation.portBase`, and `automation.portRange`, and shortcut bindings via `shortcuts.bindings.<actionId>` set to a string like `"cmd+b"`, a chord array, `null`, or `""` to unbind.

A bundled helper script (`scripts/cmux-settings`) should be used for every read and write: it strips JSONC comments, writes atomically, and validates keys against the schema. Subcommands include `path`, `dump` (with `--no-comments`), `get <a.b.c>`, `set <a.b.c> <value>` (value parsed as JSON), `validate`, and `list-supported`. Key rules: only edit `cmux.json` and never the legacy file unless explicitly asked; never tell the user to restart cmux; always validate after bulk edits; do not overwrite the non-settings top-level sections; ensure shortcut action ids match the schema enum; and use `#RRGGBB` color values with opacities in the 0..1 range. App-level preferences should first be translated to the matching JSON path.

FAQ

Which file does cmux read settings from?

`~/.config/cmux/cmux.json` (JSONC). The legacy `~/.config/cmux/settings.json` is read only as a fallback for keys not present in `cmux.json`, and should not be edited unless the user explicitly asks.

Do I need to restart cmux after changing a setting?

No. cmux installs a file watcher and reloads on save, so changes apply immediately. The skill's rules explicitly say never to tell the user to restart.

How should I read and write settings?

Use the bundled `cmux-settings` helper script for every read and write. It strips JSONC comments, writes atomically, and validates keys against the schema, with subcommands like `get`, `set`, `validate`, and `dump`.

How do I rebind a keyboard shortcut?

Set `shortcuts.bindings.<actionId>` to a value such as `"cmd+b"`, a chord array like `["ctrl+b","c"]`, `null`, or `""` to unbind. Action ids must match the schema enum, looked up in references/shortcut-actions.md.

Are there parts of the file I should not touch?

Yes. The non-settings top-level sections (`actions`, `ui`, `commands`, `vault`, `rightSidebar`) live in the same file and contain hand-tuned config, so they should not be blindly overwritten.