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

For a viewer-specific route, read the viewer matrix. It distinguishes settings-backed knobs from structural configuration and viewer types that do not have a shipped setting yet. Do not invent a templates.<viewer> path: the schema is authoritative, and the adjacent templates proposal is not a supported configuration surface until its keys appear in web/data/cmux.schema.json.

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 unless the change adds a validation issue. Issues the file already had, such as a key from a newer cmux, don't block an unrelated change; run validate to see them.

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