The orchestrator is the spine of every part on this page — one deterministic coordinator that sequences the agents, runs the gate, records the ledger, manages the worktrees, and stops on trouble.
Loom runs no LLM and never reasons about the code. That emptiness of intelligence at the centre is exactly what licenses the clever agents around it: a dumb, deterministic coordinator can be trusted to marshal an unbounded amount of intelligence.
engine ──RunEvent──▸ ┌─ TUI monitor
(worker thread, │ (live)
mpsc channel) └─ headless logger
(same stream)
One engine, decoupled by that mpsc channel of RunEvents — so the same engine drives both front-ends unchanged. Every other entry below is a part this spine drives. For how those parts flow together, see How it works.
the agents — fresh subprocesses, by role
Every unit of intelligent work is a fresh coding-agent subprocess with a clean context window — nine roles in all. Each wears a role chip; the table just below decodes those chips into the stages each role covers.
| agent | role | what it does |
|---|---|---|
| Planner | plan | Prose plan → right-sized sprint files. |
| Gate-builder | plan | Authors bin/gate, the real pass/fail check. |
| Executor | build | Implements one sprint in the worktree. |
| Fixer | build | Repairs a red gate — a bounded loop. |
| Investigator | build | On terminal failure, writes a diagnosis report, then Loom stops. |
| Reviewer | review | Applies safe fixes, flags plan-impact. |
| Re-planner | plan | Rewrites the remaining sprints when review flags plan-impact. |
| Conflict-resolver | build | Integrates main into the run branch inside the worktree on merge conflict. |
| Util agents | util | Cheap decorations: commit message, about-card, planner-card, summary blurbs. |
the four coarse roles — what each chip covers
You pick a harness per role; this is the map. The chip is the question, the table is the answer — read which stages each role covers, then jump to Harnesses to act on it.
| role | who | stages it covers |
|---|---|---|
| plan | the planners | planner · gate-builder · re-planner |
| build | the workers | execute · fix · investigate · conflict-resolve |
| review | the critic | review |
| util | decorations | commit message · about-card · planner-card · summaries |
the artifacts — what Loom produces & uses
Ground truth.
A synthesized, project-specific pass/fail script. Loom runs it itself after every code-mutating step — verified green on the clean baseline before any sprint runs.
Free resume.
The committed record of sprint status. “Done” is re-derived from it each run, so a crash costs nothing and every run is auditable.
Quarantine.
The disposable, isolated git checkout each sprint is built in. Merged to main (--no-ff) and removed only when the run is green.
The live monitor
The TUI is an activity-card feed beside a sprint rail: the current stage, per-stage card metrics, a live session view, and a ⏳ card while Loom backs off on a transient retry. Mouse-wheel scrolling throughout.
--headless --json emits JSONL with durable RFC3339 ts and "terminal": true records for parsers.
You now have the parts list. For how these pieces flow together, cross to the page of motion; for the flags that pick a harness per role, the CLI; for the role mapping itself, Harnesses.