cmux-orchestrationlisted

Verified corrections and recipes for driving cmux agent fleets from the CLI (workspaces, panes, surfaces, send/read, notify, browser). Layers on top of the cmux-shipped skills (cmux-cli, cmux-workspace) with the gotchas that actually bite. Use when spawning or orchestrating cmux workspaces/panes/agents programmatically, building an agent team, driving cmux from an external terminal, or when a cmux CLI call returns "not_found: Surface not found", "Access denied", "Unsupported browser subcommand", or a deprecation hint.
magnusrodseth/dotfiles · ★ 2 · Web & Frontend · score 65

Install: claude install-skill magnusrodseth/dotfiles

# cmux-orchestration Durable, machine-verified rules for driving cmux (manaflow-ai/cmux) agent fleets over its Unix socket. The upstream `cmux-cli` and `cmux-workspace` skills are the full reference, but they install as **unversioned real dirs that get wiped on every cmux update** and they omit the footguns below. This file lives in dotfiles (git-tracked, survives updates) and is the source of truth for the corrections. Always discover exact syntax live first: `cmux --help`, `cmux <command> --help`, `cmux docs api`. Then apply these rules. Set `CMUX_QUIET=1` to silence deprecation hints. Run every mutation with `--focus false` so you never steal the user's focus. ## The #1 footgun: refs resolve relative to the CALLER workspace Targeting a surface/pane in **another** workspace fails with `not_found: Surface not found` unless you also pass `--workspace <ref>`. This bites constantly once you have more than one workspace open. ```bash # WRONG (resolves surface:5 inside the caller's workspace, which may not exist) cmux send --surface surface:5 'ls\n' # RIGHT cmux send --workspace workspace:3 --surface surface:5 'ls\n' ``` ## Correct vs wrong (all verified) | Intent | Correct | Wrong / gotcha | |---|---|---| | Create/list/close workspace | `cmux workspace create\|list\|close` | `new-workspace` etc. still work but print a deprecation (use `CMUX_QUIET=1`) | | Target another ws's surface | `... --workspace workspace:N --surface surface:M` | omit `--workspace` → `not_found: Surf