Loop Engineering

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.

This repo documents the technique and ships the working toolkit: a Claude Code skill (skill/) that drives cmux (a scriptable macOS terminal), plus the protocol files and diagrams from a production deployment that ran 28 dispatch cycles and ~100 reviewed changes in one overnight shift.

Live visual breakdown: walidboulanouar.github.io/loop-engineering (source: docs/index.html / mermaid: docs/DIAGRAMS.md)

The loop in one paragraph

The orchestrator (one strong model) 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's CLI: "read plans/X/PLAN.md and execute it exactly" plus a callback footer. The worker (a cheap fast model with permissions pre-granted) 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.

Why it works

1. Prompts stay one line; specs live in git. The 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.
2. The callback kills polling. A finished worker is itself the wake-up signal. The orchestrator's turn simply ends after dispatching; the next WORKER-DONE message resumes it.
3. Adversarial review is a separate worker. The writer never reviews its own work. In production this gate caught fabricated benchmark variants, invented statistics (a 43% fabrication rate in generated summaries), wrong pricing tiers, and a booking button pointing at the wrong URL.
4. Cheap workers, expensive orchestrator. Workers run a fast model with --dangerously-skip-permissions inside their own panes; the orchestrator only plans, verifies, and integrates.
5. Ground truth is never the screen. Worker liveness comes from the Claude Code sessions registry and the JSONL transcripts on disk; screen reads lie when panes are hidden or the terminal restarts.

Failure modes we hit (and the fixes)

Failure	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 "succeed" into the wrong pane	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

Repo contents

skill/            The cmux-agent-manager Claude Code skill (SKILL.md + 18 shell tools):
                  spawn agents, send prompts reliably, read screens, classify agent
                  state, revive dead sessions, color-code workspaces, scan the fleet.
examples/         WORKER-PROTOCOL.md -- the standing rules + callback contract you give
                  every worker.
docs/DIAGRAMS.md  All five mermaid diagrams (full loop, callback sequence, review
                  layer, failure handling, file contract).
docs/index.html   The same breakdown as a styled single-file page.

Quick start

1. Install cmux and Claude Code. Drop skill/ into ~/.claude/skills/cmux-agent-manager/.
2. Open worker panes: claude --model sonnet --dangerously-skip-permissions in each (workers only; keep your orchestrator on your strongest model with normal permissions).
3. Find your orchestrator's address: cmux identify (workspace + surface).
4. Copy examples/WORKER-PROTOCOL.md into your repo, set your address in the callback snippet.
5. From the orchestrator: write a plan folder, then cmux send --workspace workspace:N --surface surface:S "Next task: read plans/X/PLAN.md and execute it exactly. Callback per WORKER-PROTOCOL.md." followed by cmux send-key ... enter. Verify delivery by grepping the worker's transcript under ~/.claude/projects/.
6. End your turn. The WORKER-DONE message will wake you.

Rules that keep it honest

• Every non-trivial change is logged as a bet: what changed, the measured baseline, and a check-by date for verifying whether it worked.
• Generated content gets a body-source audit (every specific claim traced to a source) before anything ships; unverifiable numbers are removed, not hedged.
• One shared working tree, no branch switching, the human merges.

MIT licensed. Built with Claude Code.