See Cmux Solve 3 Multi-Agent Orchestration Problems

1. One orchestrator agent

2. A whole window of terminals and agent teams.

3. Full programmatic control.

A hands-on showcase for anyone running Agentic Coding Agents at scale on macOS.

📺 Watch this video to get the full breakdown of this codebase: See Cmux Solve Multi-Agent Orchestration With IndyDevDan on YouTube

cmux is a native macOS terminal, built on Ghostty, for running many AI coding agents at once. This repo is 31 natural-language prompts that prove a single thesis: a primary agent (Claude Code, pi, Codex, Gemini) can stand up, prompt, observe, and tear down a whole fleet of other agents and terminals inside cmux, entirely through cmux’s CLI and socket. Prompts 1–25 climb from “open one workspace” to “run an autonomous, browser-verified, multi-window software factory”; prompts 26–31 cover customizing cmux (color-coding, theming, custom actions, layouts, sidebars, and per-pane identity). Every one was executed or schema-validated against cmux 0.64.17 before it landed here.

Start with the visual guide. Run just guide (or open guide/index.html) for the single-page walkthrough: the three proofs, the mental model, the four-verb control loop, and all 31 prompts with copy buttons. Everything below is the same study in long form.

---

The Problem — Three Things I Need From a Fleet Terminal

I run 3-tier agent teams (leads and workers), and a normal terminal fights me at every turn. Before betting on cmux I needed it to clear three bars. It clears all three, and the prompts in this repo are the proof.

1. Agentic access to every terminal window. One primary agent must be able to see and script every surface in the window: type into it, read it back, close it. Not an SDK abstraction over hidden processes, but real, addressable terminals (surface:3) the orchestrator drives directly. Why this matters so much comes later, but it is the whole foundation. → Tiers 1–5.
2. Customizable UI panes so I can tell leads from workers at a glance. A 3-tier team is unreadable if every pane looks identical. I need per-workspace color, role pill, and icon, plus per-pane identity (tab name, a colored banner, a colored prompt) so a lead never gets mistaken for a worker. → prompts 26 + 31.
3. Reusable session files that boot new teams at the speed of agents. Standing up a fresh team should be one declarative file, not ten minutes of clicking. Layouts-as-code spin up the whole roster instantly, and the fleet survives a restart. → prompts 09 + 24.

Each proof maps to a feature you can see in the visual guide (just guide) and run from prompts/.

---

Install

Agentic Install

brew tap manaflow-ai/cmux && brew install --cask cmux   # the native macOS terminal
npx skills add manaflow-ai/cmux -g -y                    # teach your agent the cmux verbs (SKILL.md files)

Then run just guide to open the visual walkthrough, or start an agent in a cmux workspace (claude, pi, codex, gemini) and paste any file from prompts/. The agent reads the cmux skills, compiles your plain English into cmux commands, and drives the fleet.

Manual Install

Prereqs: macOS 14+ (Sonoma), Homebrew, and at least one agent CLI (claude, pi, codex, gemini).

brew tap manaflow-ai/cmux
brew install --cask cmux
sudo ln -sf "/Applications/cmux.app/Contents/Resources/bin/cmux" /usr/local/bin/cmux   # use `cmux` outside cmux too
cp .env.example .env               # then fill in OPENROUTER_API_KEY / ANTHROPIC_API_KEY / etc.
open -a cmux                       # launch it

Inside any cmux terminal the cmux command already works. To let an agent drive the socket from outside cmux, raise automation.socketControlMode (see Setup & gotchas).

This repo ships a justfile with the everyday commands:

just guide          # serve + open the single-page visual guide at localhost:8080/guide/
just flotion        # boot the Flotion demo app (FastAPI :8000 + Vite :5173)
just devcc          # Claude Code orchestrator builds a 5-agent team live (/spawn-fs-team)
just devpi          # pi orchestrator does the same
just fastcc   # scripted fast path: boot all 5 panes from a layout, then attach

---

The Visual Guide

The centerpiece of this repo is one self-contained page: guide/index.html. Run just guide and it opens in your browser with no build step. It is the fastest map of everything here:

• The three proofs cmux had to clear, each paired with the feature that clears it.
• The mental model (Window → Workspace → Pane → Surface → Panel) and the four-verb control loop.
• All 31 prompts, grouped by tier, each with a copy button so you can hand one straight to your orchestrator.
• cmux vs tmux vs Warp: where the parity is, where the real moat is, and the newness tax.

Everything in the rest of this README is the long-form version of what that page shows at a glance.

---

What This Proves

Most “multi-agent” tooling hides the agents behind an SDK. cmux does the opposite: every agent is a real terminal surface you can see, and every surface is addressable (surface:3) and scriptable. So orchestration collapses to four verbs an agent already understands:

cmux send        --surface surface:3 "claude"     # type into a terminal
cmux send-key    --surface surface:3 enter        # press a key
cmux read-screen --surface surface:3              # read what it printed
cmux close-surface --surface surface:3            # shut it down

That is the entire control loop. Wrap it in a workspace, fan it across four panes, and one agent is now operating four others. The prompts in this repo were validated end-to-end: a Claude Code agent and a pi agent were launched inside cmux panes and driven to real answers over exactly these verbs. The orchestrator never touched a keyboard.

---

The Mental Model

Everything in cmux nests in one hierarchy. Learn the five boxes and the verbs fall out of them.

Window      a macOS window with its own sidebar        ⌘⇧N   cmux new-window
 └ Workspace  a sidebar entry (a "tab")                ⌘N    cmux workspace create
   └ Pane       a split region within a workspace       ⌘D    cmux new-split 
     └ Surface    a tab within a pane (terminal OR browser)  ⌘T  cmux new-surface
       └ Panel      the content itself, created automatically

The verbs every prompt is built from (the legacy new-workspace/close-workspace aliases still work):

Refs (workspace:2, surface:3) are handles you capture at creation and thread through every later call. --json gives you them machine-readable; CMUX_QUIET=1 silences the alias notices for clean scripting.

---

Reading, Deciding & Getting Notified

An orchestrator does two things a script doesn’t: it reads what an agent said and decides, and it finds out the moment something happens. cmux pushes you the discrete events; you only poll the free-form content you actually have to inspect.

# READ TO DECIDE: make the agent print a sentinel, grep it, branch on it.
cmux send --surface "$S" 'pytest -q && echo VERDICT=GREEN || echo VERDICT=RED'; cmux send-key --surface "$S" enter
V=$(cmux read-screen --surface "$S" --scrollback --lines 200 | grep -oE 'VERDICT=(GREEN|RED)' | tail -1)

# GET PUSHED: subscribe once; cmux streams one line per event (the "doorbell").
cmux events --name agent.hook --name notification.created --reconnect | while read -r e; do
  cmux read-screen --surface "$(jq -r .surface_id <<<"$e")" --scrollback --lines 40   # then read the details
done

# BLOCK ON A RENDEZVOUS: orchestrator waits, worker signals.
cmux wait-for migration --timeout 600    # ⇄  worker runs:  cmux wait-for -S migration

Full runnable cookbook (5 patterns plus a reactive dispatcher, all verified live): prompts/PATTERNS-read-and-notify.md.

The event payload is a privacy-respecting doorbell: it carries workspace_id / surface_id / notification_id and content lengths, but the title and body are redacted. Fetch the text with cmux list-notifications or by reading the surface.

---

Tier 1 — Foundations

The atomic loop: create a surface, type into it, read it back, tear it down. No agents yet, just the orchestrator and terminals.

---

Tier 2 — Driving One Agent

The pivot: the terminal an agent drives can itself contain another agent. This is the whole idea, in miniature.

---

Tier 3 — Orchestrating a Fleet

One orchestrator, many agents. Broadcast, shard, watch, react, and tear down at scale.

---

Tier 4 — Terminals Meet the Browser

A cmux surface can be a browser, with a Playwright-style API. Now agents build, run, and verify in one window.

---

Tier 5 — Scale, Remote & Resilience

The largest moves: multiple windows, organized groups, remote and cloud agents, restart survival, and the capstone.

---

Customization (26–31)

Customization is layered and ad-hoc: per-workspace identity is scriptable on the fly, the terminal’s look is a live-reloaded global, and the app’s actions/layouts/sidebar are yours to redefine, globally or per-repo via .cmux/cmux.json.

Ad-hoc, different per workspace? Yes: color, name, description, status pill, icon, progress, and layout are all per-workspace and scriptable at runtime (prompt 26). Per-pane terminal theme? No: font/theme/opacity are a single global Ghostty config (prompt 27). You differentiate workspaces by color/label (26), and panes by tab name + a printed banner/prompt (prompt 31), not by running two terminal themes side by side.

---

The Prebuilt cmux Skills

All 19 skills published in manaflow-ai/cmux are vendored into ai_docs/cmux-skills/ so you can read them. Each folder holds a SKILL.md plus references/, and several ship templates/ or scripts/. They split in two.

Agent-facing: teach an agent to drive cmux (this is what npx skills add manaflow-ai/cmux installs):

Contributor: work on the cmux codebase (vendored for completeness; not needed to run the prompts):

The nine agent-facing skills are the ones that power these prompts. Install them globally with npx skills add manaflow-ai/cmux -g -y.

---

How This Was Tested

Every prompt’s command choreography was run against a live cmux before shipping. Two real coding agents were launched inside cmux panes and driven to real output.

Both agents answered over nothing but cmux send / cmux read-screen. The thesis holds with real models.

---

Setup & Gotchas

The honest edges, all of which the prompts account for:

• The orchestrator must reach the socket. automation.socketControlMode defaults to cmuxOnly, which means an agent driving cmux must itself run inside a cmux terminal. To drive it from an outside script, raise the mode in ~/.config/cmux/cmux.json and cmux reload-config:

  { "automation": { "socketControlMode": "allowAll" } }   // or "password" + socketPassword
  

• send types, send-key submits. cmux send does not press Enter. Submit with cmux send-key enter (or end the text with \n, which send treats as Enter).
• No modifier chords. send-key sends single named keys (enter, tab, escape, arrows). There is no Ctrl-C. To stop a running agent, cmux close-surface it.
• Capture refs at creation. cmux workspace create --json returns workspace_ref + the initial surface_ref; new-split --json returns the new surface_ref. Grab and thread them; don’t guess.
• The real socket path is ~/.local/state/cmux/cmux.sock (override with CMUX_SOCKET_PATH). It is a local Unix socket, not a network port.
• Don’t inject a placeholder key over a working login. If your agent is already logged in (e.g. Claude Code), don’t --env-file a bogus ANTHROPIC_API_KEY over it. Scope .env injection to the agents that need it.
• Sandboxed agents. The Tier-1 demo prompts use a mktemp -d /tmp/… working dir and temp files (never $HOME, /usr/bin, or /var/log), so they run even when the agent has no home or bin-dir access. Point any prompt’s --cwd at a directory your agent is allowed to write.

The two config files: Ghostty owns terminal rendering (~/.config/ghostty/config); cmux owns the app (~/.config/cmux/cmux.json, plus a project-local .cmux/cmux.json). Both reload live with cmux reload-config (no restart).

Folder Structure

cmux-capabilities-guide/
├── guide/                        # ⭐ the centerpiece — run `just guide` to open it
│   ├── index.html                #   one self-contained page: proofs, model, control loop, 31 prompts w/ copy buttons
│   ├── cmux-guide.pdf            #   the same guide, paginated for offline / print
│   └── images/                   #   themed section diagrams + the hero SVG
├── prompts/                      # the 31 prompts in long form (25 fleet + 6 customization)
│   ├── 01-hello-workspace.md     #   Tier 1 — foundations (01–05)
│   ├── …                         #   Tiers 2–5 — one agent · fleet · browser · scale (06–25)
│   ├── 26-color-code-and-label.md#   Customization — identity, theme, actions, layouts, sidebar (26–31)
│   └── PATTERNS-read-and-notify.md  # read-to-decide + push/notify cookbook
├── ai_docs/
│   └── cmux-skills/              # all 19 prebuilt cmux skills, vendored for inspection
├── apps/flotion/                 # the demo app the agent team builds (Vue 3 + TS / FastAPI + SQLite)
├── cmux/fs-team.layout.json      # declarative layout that boots a 5-agent team in one call
├── scripts/spawn_fast.py         # uv single-file script behind `just fastcc` / `just fastpi`
├── images/                       # the diagrams reused as README section art
├── .claude/                      # /prime, /spawn-fs-team, the 5 agent roles, and the cmux skill
├── justfile                      # `just guide` · `just flotion` · `just devcc` · `just fastcc`
├── .env.example                  # provider API keys an orchestrator injects to kick off sub-agents
└── README.md                     # you are here

Each prompt file is self-contained: the plain-English prompt you hand your orchestrator, an answer-key of the exact cmux verbs it should compile to, and success criteria you can check.

---

License

MIT — see LICENSE.

---

Master Agentic Coding

Prepare for the future of software engineering.

Learn tactical agentic coding patterns with Tactical Agentic Coding.

Follow the IndyDevDan YouTube channel to improve your agentic coding advantage.

---

Stay Focused and Keep Building

• IndyDevDan