---
title: Parallel coding agents on one machine
summary: Run several coding agents at once without them colliding: a worktree, a test database, dev ports and a profile dir each, then review, merge one at a time and run every flow
when_to_use: A redesign split by screen group, a bug sweep with many independent fixes, or any batch of changes that don't touch the same files
prerequisites: A git repo with tests and browser flows; a local Postgres; enough usage headroom on your AI plan (parallel sessions share one limit)
related: [workflows/browser-flow-testing.md, workflows/design-first.md, workflows/agent-pipeline.md, reference/working-with-ai.md]
last_verified: 2026-09-26
---

# Parallel coding agents on one machine

## Goal

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.

## Inputs

- A split of the work into groups that **don't touch the same files** (by screen
  group, or by bug cluster)
- The list of shared state each agent's tests touch: databases, ports, caches, auth
  rate limits, browser profile dirs, files in `/tmp`

## Steps

1. **Land 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.

2. **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.

3. **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.

4. **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.

5. **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.

6. **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.

7. **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.

8. **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.

9. **Deploy once, then verify on production** with a test account.
   **Check:** the flows touching the changed screens pass against the live site.

## Traps

| 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 |

## Done when

- [ ] Every agent had its own worktree, test DB, dev port, browser port and profile dir
- [ ] Branches merged one at a time with the full test + flow suite green after each
- [ ] Worktrees and temp databases removed
- [ ] One deploy, verified on production with a test account