Agent Orchestration Pattern
Run a fleet of Claude Code agents from one orchestrator session, in a plain terminal multiplexer, with no framework, no queue service, and no polling. Plans live in git, reviews are adversarial, and finished workers wake the orchestrator by typing into its terminal.
The orchestrator picks the next lever from data, writes a plan folder
(plans/<name>/PLAN.md) and commits it, then sends one line to a worker
pane over the terminal multiplexer CLI. The worker does the work, writes
RESULT.md into the same folder, and as its
last action types WORKER-DONE X: <status> into the
orchestrator's own terminal and presses enter. That message arrives as a user
prompt, so the orchestrator wakes instantly, harvests the result, logs the change as a bet
in a ledger (baseline + check-by date), and immediately re-tasks the idle worker.
Nobody polls anything.
Section 01
One orchestrator on the strongest model plans, commits, dispatches, and logs. Workers on a fast model execute inside their own panes. The loop is driven entirely by worker callbacks - no timer, no watcher process.
Section 02
The orchestrator never polls. Each worker prompt ends with an instruction to re-prompt the orchestrator's own Claude Code session through cmux when finished. The worker literally types into the orchestrator's terminal. The callback text is one line: plan name + status. The real payload always lives in the plan folder's markdown files.
cmux send --workspace workspace:8 --surface surface:22 \ "WORKER-DONE <plan>: <status>" cmux send-key --workspace workspace:8 --surface surface:22 enter
Section 03
A worker never reviews its own work. In production, adversarial review caught fabricated benchmark variants, a 43% fabrication rate in generated summaries, wrong pricing tiers, and a booking button pointing at the wrong calendar URL.
Section 04
Ground truth is never the screen. The sessions registry and the workers' JSONL transcripts decide who is busy, who died, and what was delivered. Screen reads lie when panes are hidden or the terminal restarts.
| Failure mode | Fix |
|---|---|
| Terminal restart renumbers every pane | Re-map with cmux tree, interrupt misrouted agents with escape, re-dispatch |
| Worker session dies silently on an API error | Registry shows idle + no RESULT file: reassign the plan to another worker |
| Worker context window fills mid-task | /exit, relaunch fresh, resend the one-line prompt (the plan folder has everything) |
| Sends into the wrong pane after a restart | Verify every dispatch by grepping the worker's transcript for the plan name |
| Multiplexer UI thread freezes entirely | Fall back to headless claude -p workers; task notifications replace callbacks |
Section 05
Plans live in git. Every plan folder is the contract, the backup location, and the audit trail. Re-dispatching after any failure is trivial because state is on disk, not in a conversation.
Key Rules
Six rules that prevent the common failure modes and keep the loop honest.
One plan folder per task. The prompt only says "read PLAN.md and execute it exactly" plus the callback footer. Prompts stay short; specs live in git.
Cheap workers, expensive orchestrator. Workers run Sonnet with
--dangerously-skip-permissions; the orchestrator is the only expensive
model and only plans, verifies, and integrates.
Every worker prompt ends with the callback.
cmux send --workspace workspace:8 --surface surface:22 "WORKER-DONE <plan>: <status>"
then cmux send-key ... enter. Blocked workers send
WORKER-BLOCKED instead.
Verify every dispatch. Grep the worker's transcript for the plan name. cmux sends can time out yet deliver, or succeed into the wrong pane after a restart renumbers surfaces.
Shared working tree. No worker ever switches branches; all commits ride the current branch and a single PR the human merges.
Every non-trivial change gets a ledger entry with a measured baseline and a check-by date, so a future session verifies whether the bet paid off.