Zero to a running build in four steps and about five minutes. Write a prose plan, launch Loom, watch it build, and review when it pings you — copy-paste from the top.
-
Write a prose planAn ambitious markdown file describing intent, scope, and what "done" looks like. Don't pre-split it into sprints — Loom's planner owns that.
-
Launch LoomRun
loom feature-plan.mdfor the live monitor — or--headless/--detachfor the other two forms below. -
Watch it build
loom listto find it,loom logs <name> -fto follow,loom status <name>to re-orient. -
Review when it finishesA green run merges the worktree to main and removes it; the ledger shows DONE.
Three checks before you launch — most repos already pass all three.
A git checkout with a clean enough baseline for a disposable worktree.
The harness CLI you'll use is already authenticated — default is Claude Code's claude. Loom uses whatever auth that CLI already has; pick a harness per role on Harnesses.
Optional but recommended: bubblewrap installed for the agent sandbox — setup on Help / sandbox.
step 2 · pick your launch line
All three build the same plan — they differ only in where the run lives and how you watch it.
Interactive — the live TUI monitor
Headless — plain line output: cron, remote, piped
Detached — outlives your shell: fire-and-forget
step 3 · watch it build
Four one-liners. <name> is the short, copy-pasteable handle every run carries.
| command | args | what it does |
|---|---|---|
| loom list | (ls) | table of every run — name, state, sprint progress |
| loom logs | <name> -f | tail the activity journal; -f follows until the run is no longer active |
| loom status | <name> | title, state, sprint progress, ledger — the cold re-orient command |
| loom enter | <name> | open a shell in the run's worktree |
step 4 · when it finishes
A green run finished.
Loom merges the worktree to main (--no-ff) and removes it; the committed ledger shows DONE. Nothing left to do — the work is on main.
A run stopped.
Loom leaves a by-hand message naming the worktree and branch, and writes an investigate report under .loom/<plan>/reports/ — read it, fix the cause, and re-run.
Nothing to fear: a plain re-run resumes. It reuses the worktree and ledger and skips the sprints already marked DONE — so you only ever lose the in-flight one.
To start over instead of resuming:
--clean and --remove dry-run by default — they print what they would delete and ask first; add --yes (-y) to skip the prompt.
Driving Loom from inside another agent session? Run a plain headless run backgrounded by your harness — not --detach — so the harness wakes you the moment the run ends and you can review it. And don't impose a short timeout: a run can take hours, and a foreground deadline will reap it mid-build.
This page walks the one happy path. For the full surface, follow the exits.