Agent Orchestrator Cockpit

CMUX

Make cmux the cockpit for every agent — LifeOS's own and your hands-on coding teams. One command boots a named, color-identified workspace of agents you can see, prompt, and steer, because an agent you can't see is an agent you can't improve. {{DA_NAME}} drives them through cmux's real send/read/open-close loop; a poll-based monitor speaks up when they finish.

Everything routes through one wrapper: bun ~/.claude/skills/CMUX/Tools/cmux.ts <subcommand>. It auto-launches the cmux app — but cmux's socket is default-deny, so driving it needs auth (see the first Gotcha).

Status (2026-07-07): built and offline-verified — wrapper is type-clean (tsc/bun build), voice works live, public-clean grep passes, Kitty hooks untouched. Live-driving (boot-team/race/fleet/monitor) is UNPROVEN — it needs the socket-auth handshake, which has not yet executed. To prove it: run the wrapper inside a cmux surface (inherits auth), or set a cmux Settings socket password → CMUX_SOCKET_PASSWORD. Security note: a socket password lets any local process holding it drive your whole agent fleet — set it deliberately and never commit it to a public file.

Workflow Routing

Trigger	Workflow
"boot a team", "3-tier team", "orchestrator/lead/workers"	Workflows/BootTeam.md
"race agents", "hotfix race", "throw N agents at this", "needle in a haystack"	Workflows/AgentRace.md
"fleet", "2x2 fleet", "named teams", "the remote fleet", "mini-fleet"	Workflows/Fleet.md
"watch/monitor my agents", "tell me when they're done", "observe to improve"	Workflows/Monitor.md

Quick Reference

CT=~/.claude/skills/CMUX/Tools/cmux.ts
bun $CT ping                                             # ensure cmux is up (auto-launches)
bun $CT boot-team --name debug --tiers orchestrator,lead,worker,worker
bun $CT race --feature login-500 --agents 4             # first-to-solve wins
bun $CT fleet --name alpha --grid 2x2 --cmds "claude;codex;claude;bun test --watch"
bun $CT mini-fleet                                       # SSH panes from USER fleet.json
bun $CT send --surface workspace:1/surface:2 "run the tests" --enter
bun $CT read --surface workspace:1/surface:2 --lines 40
bun $CT monitor --workspace workspace:1                  # poll + {{DA_NAME}} voice on done
bun $CT flash --workspace workspace:1                    # visual attention

The loop that makes it work: send (type a prompt) → send-key Enter (submit — --enter does both) → read (see the result) → close-surface (tear down). That send/read/open-close cycle is the whole programmatic-access story; the recipes are just it, composed.

What stays underneath (not replaced): Pulse (localhost:31337) is still the dashboard, {{DA_NAME}} voice still fires via /notify, the Algorithm/ISA/memory/model-routing are untouched. cmux replaces the terminal-watching layer, not the system. See DESIGN.md for the full feature map and the staged Kitty→cmux migration.

Gotchas

• send types but does not submit. cmux send puts text in the surface; it does not press Enter. Always use --enter (or a follow send-key Enter) when you mean to run the prompt, then read to confirm it actually ran. A send with no Enter that claims "the agent is working" is a false done-claim.
• The socket is default-DENY — this is the #1 gotcha. Even while the app runs, an outside process gets Access denied — only processes started inside cmux can connect. Two ways through: (a) run the orchestrator inside a cmux surface — it inherits auth via a tagged CMUX_SOCKET_PATH env, no password; or (b) set a socket password in cmux Settings and export it as CMUX_SOCKET_PASSWORD (the wrapper passes --password). The socket also only exists while the app runs (cmux.sock absent when closed). Pick (a) for agent-driven work, (b) for external scripting.
• cmux is push-native — prefer hooks over polling. Launch Claude agents with cmux claude-teams and cmux auto-injects Claude Code lifecycle hooks (SessionStart/Stop/Notification/UserPromptSubmit/... → cmux claude-hook <event>), so agents report their own status. Also available: tmux-style set-hook <event> <cmd>, a blocking wait-for -S <name>, pipe-pane --command, and OSC 9/99/777 escapes. monitor's surface-health + read-screen poll is the FALLBACK for non-Claude agents, not the primary path.
• Sidebar metadata is a no-auth Pulse bridge. report_meta / report_meta_block / set-status / set-progress / log write agent status/progress into the workspace sidebar and persist to the session JSON at ~/Library/Application Support/cmux/session-*.json — which is readable without the socket. LifeOS reads that file to mirror cmux agent state into Pulse without touching the auth wall.
• Mac-only. cmux is a macOS app. The remote fleet still runs LifeOS, but cmux drives it via local SSH panes, not by running cmux on the minis. No Linux/WSL — that path is tmux.
• Refs are positional and can shift. workspace:1/surface:2 indexes move as you open/close things. For anything long-lived, resolve UUIDs (--id-format uuids) from tree and hold those.
• Public skill — private specifics live in USER config. The remote fleet's hosts come from ~/.claude/LIFEOS/USER/CUSTOMIZATIONS/SKILLS/CMUX/fleet.json ({"hosts":[{"name","ssh"}]}), never from this skill's files. The socket password comes from CMUX_SOCKET_PASSWORD.

Examples

Boot a debugging team and drive the lead:

User: "boot a cmux team to chase the flaky test"
→ bun $CT boot-team --name flaky --tiers orchestrator,lead,worker,worker
→ bun $CT send --surface <lead-ref> "find why auth.test.ts flakes; delegate repro to a worker" --enter
→ bun $CT monitor --workspace <ws>   # {{DA_NAME}} voice when the lead reports back

Race a production hotfix:

User: "prod login is 500ing — race it"
→ bun $CT race --feature login-500 --agents 4
→ (four agents attack the same repo; first with a root cause wins)
→ bun $CT read --surface <winner> ; close the losers

Full reference for the migration and feature map: DESIGN.md.