Loom turns a prose plan into a finished, merged build through a fixed pipeline of fresh agents — with a deterministic orchestrator in the middle that never touches the reasoning.
Read it as a key. Amber ▸ is a stage running; green ✓ is a stage that passed its gate; red ✗ STOP is the run halted on trouble. The panels below decode each cue in order — the loop is safe by structure, not by promise.
One run, plan to merge. Each numbered stage hands off to the next; the orchestrator carries the continuity and the committed ledger carries the state — no single agent holds the whole plan.
A planning agent reads the prose plan and writes a set of right-sized sprint files (.loom/<plan>/NN-slug.md). You don't pre-split the work — the planner owns that.
A gate-builder agent authors bin/gate — a real pass/fail check. Loom runs it itself on the clean baseline and confirms it's green before any work starts.
A fresh agent executes the sprint in its worktree; then Loom gates it. A red gate forks into the fix loop, a green gate into review (both drawn just below). Done sprints are re-derived from the ledger and skipped. Each finished sprint is committed and marked DONE.
When the whole run is green, Loom merges the worktree to main (--no-ff) and removes it.
The gate decides the branch
Every code-mutating step is followed by the gate — and Loom runs the gate, not the agent. The result is grounded in a check Loom executes itself, never the agent's self-report.
Red opens the bounded fix loop: a fix agent runs, Loom re-gates. Still red, an investigate agent writes a diagnosis report and the run STOPs rather than guessing onward.
Green opens review: a review agent applies safe fixes and flags plan-impact. If it touched code, Loom re-gates; if it flagged plan-impact, Loom re-plans the remaining sprints on the fly. Then the sprint is committed and marked DONE.
worktree ──build──▸ gate Loom runs it
│
┌───────────┴───────────┐
red green
│ │
▼ ▼
fix review
│ │
gate again re-gate · re-plan
│ │
still red ▼
│ commit ▸ DONE
▼ │
investigate all green
│ │
▼ ▼
STOP ✗ merge --no-ff ▸ main
The gate is the keystone
"Done" means gate-green and committed — re-derived from the committed ledger each run, so a crash costs nothing and resume is just re-running loom. Continuity lives in the orchestrator; state lives on disk.
Coding agents are great at thinking and planning, and bad at carrying out anything complex — because a context window fills fast. Past 200k–300k tokens the model turns slow and dim, yet keeps going as if nothing were wrong. Fanning out to sub-agents barely helps: the top-level agent fills its own context just reading their output. Beyond a five-minute fix, the operator ends up spending more effort nursing context budgets than thinking about the actual work.
Loom's answer is to make a single agent's context window stop being the ceiling. It gives every unit of intelligent work a clean context window — execute, fix, investigate, review, re-plan, conflict-resolve are each a fresh coding agent — and puts a plain, context-immune script at the top instead of a steadily-rotting agent. No single agent holds the whole plan: the orchestrator carries the continuity, the ledger carries the state, and state-of-the-art reasoning is invoked exactly where it's needed.
Isolated worktrees & merge-back
Every sprint is built in a disposable git worktree, never the main checkout. When the whole run is green, Loom merges that worktree to main and removes it — so an in-flight change is quarantined off to the side until it is proven green.
Conflict handling. If main moved under a long run, Loom resolves the conflict entirely inside the disposable worktree: it snapshots main, integrates main's tip into the run branch there, runs the conflict-resolver agent, then re-gates. Only a clean, gate-green result merges. If it can't be made clean, Loom restores main to its exact pre-merge state and stops with a by-hand message — your main checkout is never left dirty.
main moved under a long run
│
▼
snapshot main
│
▼
integrate main's tip ──▸ run branch
│ (inside the worktree)
▼
conflict-resolver agent
│
▼
re-gate
│
┌───────┴────────┐
green red / unclean
│ │
▼ ▼
merge clean restore main to its
▸ main exact pre-merge state
│
▼
STOP ✗ — by hand
(main never left dirty)
The orchestrator holds no intelligence
Loom sequences the agents, runs the gate, records the ledger, manages the worktrees, and stops on trouble — and reasons about none of the code. That separation is the whole design.
run it — one line, headless
The default driver decomposes a plan into milestones. Force the flat sprint pipeline with --sprints, or force the milestone driver explicitly with --milestones — see the CLI reference for the full flag surface.
This page is the page of motion and causation. For what each piece is, read Components; to run Loom yourself, take the Quickstart.