What does this skill do, and when should you use it?
This is the Agent Skill at skills/cmux-settings in the manaflow-ai/cmux repository, dedicated to cmux's user configuration file ~/.config/cmux/cmux. (JSONC). It uses a bundled helper script to read, write via dotted JSON paths, validate, and atomically save configuration; a file watcher hot-reloads changes on save with no restart. The skill builds in schema validation, undo receipts, and --preview, and explicitly forbids touching non-settings sections like actions, ui, and commands that share the file. It fits developers already using cmux, the Ghostty-based native macOS terminal.
- Reads the config path, raw file (comments preserved), or a specific value via cmux-settings path/dump/get
- Sets or removes values at dotted JSON paths with cmux-settings set/unset, parsing values as JSON, validating before writing
- Runs the same semantic validation as the app via cmux-settings validate (unknown paths, types, enums, bounds)
- Enables reversible edits via --preview/--expect-revision/--receipt plus undo
- Lists every settings path the app recognizes with list-supported; shortcut action IDs live in references/shortcut-actions.md
- Opens cmux. in $EDITOR, VS Code, Cursor, or TextEdit with cmux-settings open
- A developer running multiple AI coding agents in cmux wants to persist preferences like sidebar details, notification sounds, or browser defaults into the config file
- Rebinding a keyboard shortcut (e.g. new tab to ctrl+b c) without guessing the action ID
- Writing a distributable cmux configuration for a team, validating before it lands and rolling back if needed
- Editing keys whose names contain dots (like a workspaceGroups.byCwd entry for ~/src/app.web), which the path-splitting commands refuse
- Packaging an uninstallable preset change with a --receipt undo file
- Anyone not using the cmux terminal — the skill serves only ~/.config/cmux/cmux. and is useless without it
- Linux/Windows users — cmux is macOS-only
- Users wanting to change runtime/UI state (browser profile import, per-page navigation, current right-sidebar tab) — these have no settings keys and need browser/sidebar commands or the Settings pane
How do you install this skill?
- This is a static source-only review; no script was executed. The main helper script itself is absent from the evidence, so actual behavior is unreproduced.
- references/all-keys.md self-declares it may lag the authoritative schema; prefer list-supported or the schema when looking up keys.
- There is no user-confirmation step before writes; an agent can modify user config directly. Undo exists, but review changes manually in sensitive scenarios.
- The schema is fetched from raw.githubusercontent.com, which is often unreachable from mainland-China networks; failure behavior when the fetch fails is not documented.
- Target environment is macOS with cmux installed; the skill does not fit other environments. Repository licensing is a GPL-3.0 / partial-BUSL-1.1 split while license metadata reads NOASSERTION — verify before commercial use.
- Publisher is not verified by the FollowSkills registry and is treated as unknown.
- Shell / CLI
- Local filesystem
cmux app (macOS) with ~/.config/cmux/cmux.bundled cmux-settings helper script (or the installed cmux CLI)
The source documents no standalone install commands; this skill is one of 25 bundled in the cmux repository. Two usable routes:
Codex (installed path, as written in SKILL.md):
~/.codex/skills/cmux-settings/scripts/cmux-settings <subcommand>Any Agent Skills client / from a checkout:
git clone https://github.com/manaflow-ai/cmux
cd cmux
git checkout skills/cmux-settings/SKILL.md
export PATH="$PWD/skills/cmux-settings/scripts:$PATH"Prerequisite: the cmux app (DMG or brew install --cask cmux) installed with ~/.config/cmux/cmux. present.
How do you use this skill?
Once installed, send your agent any of these to trigger it:
- Set cmux sidebar background to match the terminal theme: cmux-settings set sidebarAppearance.matchTerminalBackground true, then validate and tell me how to undo it
- I want to disable notification sounds in cmux. — first list all notifications-related keys
- Rebind the cmux new-tab shortcut to ctrl+b c
- Preview what setting app.appearance to dark would change, then confirm with a receipt I can undo later
The skill triggers on phrases like 'cmux config', 'cmux.', 'change cmux setting', 'rebind a cmux shortcut', or the '/cmux-settings' command. Standard flow: look up the key with list-supported, set it, read back, then validate. Values are parsed as JSON (true, 42, "text", arrays, objects); unquoted plain words are stored as strings.
cmux-settings list-supported | rg -i 'sidebar.*terminal'
cmux-settings set sidebarAppearance.matchTerminalBackground true
cmux-settings validate
cmux-settings unset sidebarAppearance.matchTerminalBackgroundReversible variant: bash
cmux-settings set app.appearance dark --preview
cmux-settings set app.appearance dark --receipt ~/private/undo.
cmux-settings undo ~/private/undo.
Notes: the JSON output of set/unset records only what reached disk, not the running app's reload; paths split on every '.', so keys containing dots are refused — edit those directly in the file.
What are this skill's strengths and limitations?
- Forces full semantic validation and atomic writes, never introducing new validation issues
- File watcher hot-reloads on save — no restart ever needed
- Undo receipts with --expect-revision give genuinely reversible edits; receipts are mode-0600
- Shares one schema and write path with the cmux CLI's config get/set/unset/toggle/cycle and preset commands
- Covers only settings sections; non-settings config (actions/ui/commands/vault/rightSidebar) must be hand-edited carefully
- Keys whose names contain dots cannot be edited via CLI paths — direct file editing required
- No standalone versioning or release channel; maintained bundled with 24 sibling skills in the monorepo
- License is NOASSERTION; the repo is GPL-3.0-or-later overall with web/ under BUSL-1.1 — no separate license is declared for the skill
How does this skill compare with similar options?
Side by side with related skills; every score comes from the same FSRS standard.
| Skill | FS score | Stars | Last updated | License |
|---|---|---|---|---|
| cmux Settings Management Skill (cmux-settings) this page | 58 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Keyboard Shortcuts | 58 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Customization | 55 · Use with care | ★ 28k | 1d ago | NOASSERTION |
| cmux Workspace Skill | 64 · Recommended | ★ 28k | 1d ago | NOASSERTION |
| cmux Diagnostics | 51 · Use with care | ★ 28k | 1d ago | NOASSERTION |
The source names the alternatives directly: the plain cmux config get|set|unset|toggle|cycle CLI (covers common edits but lacks --preview, receipts, undo, and alternate file targets) and hand-editing cmux. (no validation, error-prone). The skill is essentially the same operations wrapped with safety guardrails.
How did FollowSkills review this skill?
Evidence shows least privilege (edits only the user's own cmux.), full validation before writing, atomic writes, explicit rollback via --preview/--receipt/undo, mode-0600 receipts with a privacy warning; deducted for: no user-confirmation step (an agent can rewrite config directly), --file can target arbitrary paths, network-fetched external schema with unstated failure behavior, and unverified publisher.
SKILL.md workflow is self-consistent with well-designed failure feedback (structured conflict/invalid_config outputs, undo_conflict preserving newer values); the JSONC mutation script handles duplicate keys, comments, and newline edge cases; deducted for: static-only review cannot reproduce key paths, the main helper script itself is not included in evidence (only its referenced Python module and message file), all-keys.md self-declares possible lag behind the schema, and the Swift fallback path for list-supported is unverified.
Frontmatter triggers are explicit (/cmux-settings, cmux., rebind shortcut, etc.) with clear non-fit boundaries (viewer runtime/UI state, the templates proposal, keys containing dots); deducted for: macOS + installed-cmux prerequisite without stated dependency detection or failure guidance, and no explicit note on mainland-China reachability — the schema is fetched from raw.githubusercontent.com, which is often unreachable there.
Good layering (SKILL.md + reference matrix + authoritative schema + quick reference), stable naming, a Rules section; deducted for: no skill-level version or changelog, repository license metadata is NOASSERTION (actual licensing is a GPL-3.0 / partial-BUSL-1.1 split the reader must disentangle), all-keys.md self-declares schema drift, and maintenance ownership/update path is only visible at repo level.
Core task (look up, set, validate, revert cmux settings) has a complete flow with defined output formats (JSON results, structured errors) and clear marginal value over manual JSONC editing (comment preservation, protection of non-settings sections, receipt-based undo); deducted for: no execution evidence that outputs are directly usable, example values depend on actual app behavior, and the comparative-benefit claim is unverifiable statically.
Key claims trace to in-repo material (schema path, Swift source file, a declared test file tests/test_cmux_settings_supported_paths.py, cross-referenced docs); deducted for: no third-party execution evidence, no CI or test contents provided in evidence, referenced files (viewer-types.md, full all-keys.md) not fully attached, so key claims cannot be independently rechecked.
Open a dimension to read why it scored that way
Evidence confidence：Low — Mostly static review, author material or a limited demo; useful for discovery, not high-risk decisions.
See the full review method →