N agents work side by side, each on its own branch, and their branches merge cleanly into one release. No agent's tests fail because of another agent. Two real runs this held for: a full redesign split into screen groups, and a 15-bug sweep done by 5 agents in one morning (one PR, 58 files).
main (shared primitives land here FIRST)
│
┌──────────┬───┴──────┬──────────┬──────────┐
▼ ▼ ▼ ▼ ▼
wt/a wt/b wt/c wt/d wt/e git worktrees
test_a test_b test_c test_d test_e own test DB
:5174 :5175 :5176 :5177 :5178 own dev port
cdp 9301 cdp 9302 cdp 9303 cdp 9304 cdp 9305 own browser port + profile
└──────────┴──── review screenshots, merge ONE at a time, run ALL flows ───▶ deploy
Worktrees isolate files, not databases, ports or rate limits. Everything below is about the parts they don't isolate.
/tmpLand the shared pieces first, on main. For a redesign: the primitives
(buttons, inputs, sheets, labels). For a bug sweep: any migration two fixes both need.
Check: every agent will branch from a main that already has them. No agent
should need to invent its own button.
One git worktree + branch per agent.
git worktree add ../wt-a -b fix/group-a main
Check: git worktree list shows N entries, each on its own branch.
One test database per agent. If API tests truncate tables before running,
agents sharing one test DB wipe each other's rows mid-test, and passing code fails.
bash
for s in a b c d e; do createdb <app>_test_$s; done
# in each worktree: api/.env.test → DATABASE_URL=…/<app>_test_<s>; then apply migrations
(cd ../wt-a/api && set -a && . ./.env.test && npx prisma migrate deploy)
Check: each worktree's tests pass alone and while another agent's tests run.
Unique ports per agent: dev server (vite --port 517N), the browser's
remote-debugging port (make the flow script read CDP_PORT from env), and a browser
profile dir under that agent's own scratch folder, deleted after the run.
Check: no "port in use" errors; no flow ever attaches to another agent's browser.
Handle shared rate limits. Flows that sign up a fresh user each run will hit an auth limiter (e.g. 10/min per IP) once several run close together. The failure looks like a real bug. Either space runs about a minute apart, or run one shared local dev API with a raised limit (dev only, never production). Check: a burst of flows from all agents passes signup.
Brief each agent narrowly: its group, the files it may touch, "reuse the primitives", which flows must pass, "don't merge, don't deploy". Tell it which model to use if your plan is tight. Check: each brief names its done-when list and its forbidden files.
Review, then merge one branch at a time. Look at each agent's screenshots
and diff yourself. After each merge, run typecheck, unit tests and every
browser flow, not only the ones for the merged screens.
Check: main is green after every single merge, not only after the last.
Clean up worktrees before building or deploying. Linters and some build
tools walk the whole tree. Leftover .claude/worktrees/* or ../wt-* copies inside
the repo get linted and fail the deploy's lint step.
git worktree remove ../wt-a (and git branch -d once merged).
Check: git worktree list shows only the main checkout; the deploy's lint passes.
Deploy once, then verify on production with a test account. Check: the flows touching the changed screens pass against the live site.
| Symptom | Cause | Fix |
|---|---|---|
| Tests fail randomly in one worktree, pass alone | a shared test DB being truncated by another agent | one test DB per agent (step 3) |
| Third flow in a row fails at signup | auth rate limiter doing its job | space runs, or raise the limit on the local API only |
| Flow screenshots show another agent's screen | shared browser debugging port / profile | CDP_PORT + profile dir per agent |
| First run after a migration fails everywhere with 500s | a shared local API started earlier from old code, without watch mode | restart shared services after any migration; check that no other session owns them |
| Deploy lint fails on files you never touched | agent worktrees inside the repo are being linted | remove worktrees first, or exclude them in lint config |
| Everything stops with a usage-limit error | N parallel sessions share one plan window | fewer agents, cheaper model for mechanical groups, say the cost first |
Merged main breaks a screen no agent touched |
behaviour lost in a rebuilt shared component | run every flow after each merge |
| Another human/AI session is editing the same repo | nobody said so | check git status / git log for work you didn't make before merging or deploying |