CMUX for Multi-Agent Orchestration: Run Agent Fleets from One Terminal

Step-by-Step Breakdown

1. Start from the problem, not the tool

   IndyDevDan names three multi-agent orchestration problems most builders hit: (a) no programmatic access to your agents, which makes you the bottleneck; (b) no way to see and monitor agents, so you can't improve them — "an agent you can't see is an agent you can't improve"; and (c) booting agent teams by hand kills agentic speed. CMUX is evaluated against these three, not adopted for its own sake.

2. Learn the CMUX mental model

   Four nested units: Window (control+shift+N) → Workspace (command+N) → Pane → Surface/tab (command+T opens a new surface inside a pane). He puts whole agent teams at the workspace level, the lead on the left pane, and worker agents on the right — so he can zoom to the level he needs without losing visibility into low-level workers.

3. Give the agent a CMUX skill

   A small "CMUX skill" makes the orchestrator agent aware of the tool. The control loop is four actions: send (send-key text into a surface), read (read the screen after the action completes), and open/close surfaces — then repeat. Because it's fully scriptable, you drive it in natural language with well-constructed prompts.

4. Drive a single orchestrator over one workspace

   He has the orchestrator open a workspace in a fresh temp directory, create mock files, run ls, and read the output back — all without typing into that window himself. You can still jump in and touch the terminal at any time, which is the point of "agentic access": no black boxes.

5. Scale to a fleet

   He boots Claude Code and the Pi coding agent side by side, then a four-agent "security fleet" — Claude Code, Codex, Pi running Minimax M3, and Pi running GLM 5.2 — all executing the same prompt: "list the top three security vulnerabilities in this repository." Different tools and models attack the same task in parallel and fully visible. This is his "scale your compute to scale your impact" pattern.

6. Flat agent-to-agent communication

   Any agent can prompt any agent via the CMUX skill — e.g. a Claude Code worker pings its fleet co-workers by reading each surface. Even with an orchestrator at the top, the communication channel is flat rather than strictly top-down. Notification events fire to a top window when an agent completes so you can work elsewhere and get pulled back in.

7. The "race" pattern for hot fixes

   For a production-down emergency, stand up an eight-agent race across workspaces and have them converge on a solution in parallel (a needle-in-a-haystack / capture-the-flag task). Take the first correct answer and ship the hot fix. Throwing diverse intelligence — different tools, models, contexts — at one urgent problem tends to win.

8. One-tap relaunch with a justfile

   A just recipe boots a full team instantly. He runs just fast cc <feature> to spin up his preferred three-tier structure: an orchestrator, team leads (one shown on GLM 5.2), and each lead's worker agents (plan, build, build-frontend, test). The extra hierarchy level is what T-mux couldn't organize cleanly for him.

Commands & Code Shown

control + shift + N

control + shift + N

Purpose: Open a brand-new CMUX window (the top-level container).

When to use: When you want a fully separate surface for an unrelated stream of work.

command + N

command + N

Purpose: Create a new workspace. IndyDevDan puts each agent team on its own workspace.

When to use: Every time you stand up a new team or a new feature/bug-fix effort — prefer new workspaces over new windows.

command + T

command + T

Purpose: Open a new surface (tab) inside an existing pane.

When to use: To add another terminal alongside an agent without leaving the current pane layout.

hold command

hold command

Purpose: Reveal the hotkeys for each workspace — CMUX treats the workspace as the primary navigation unit.

When to use: When you need to jump quickly between many workspaces of running agents.

CMUX skill (send / read / close-surface API)

send key  → read screen → open/close surface → repeat

Purpose: The programmatic control loop the orchestrator agent uses to operate every terminal.

When to use: This is the core of agentic access — install the skill so an agent can drive CMUX in natural language.

just fast cc <feature>

just fast cc <feature>

Purpose: A justfile recipe that instantly boots a three-tier agent team (orchestrator → leads → workers) focused on the named feature.

When to use: For the thousandth agent-team launch — turns repeated multi-agent setup into one command.

Common Errors & Fixes Covered

Gotchas & Caveats

• Mac-only. On Linux, Windows, or WSL, use T-mux instead — CMUX targets macOS.
• It's a new, fast-moving tool. Expect bugs and maturity gaps; compare it against tried-and-true T-mux before committing.
• "If a tool has no programmatic access, ignore it." Agentic access is the whole value — without it you're stuck moving at human speed.
• Don't run fleets you can't see. "An agent you can't monitor is an agent you can't improve" — the visibility is what separates agentic engineering from vibe coding.

Key Takeaways

• CMUX is a scriptable terminal multiplexer purpose-built for orchestrating coding agents programmatically on macOS.
• The three-tier pattern — orchestrator → team leads → worker agents — runs on a flat comms channel where any agent can prompt any agent.
• Its differentiator over T-mux is developer experience and pluggable notification events, not raw capability.
• Mixing agent tools and models (Claude Code, Codex, Pi with GLM 5.2 / Minimax M3) against one task yields diverse, comparable results.
• "Scale your compute to scale your impact" — parallel agent races are a fast way to resolve urgent hot fixes.