Parallel Coding Agents with Git Worktrees

Tier: Advanced · Workflow area: Feature development

Production teams report roughly half to two-thirds of overnight agent branches arriving merge-ready; the craft is picking tasks and running the review loop so the failures cost you minutes, not mornings.

When to use

• •
  A backlog of well-specified, independent tasks: bug fixes with reproductions, test-coverage lifts, mechanical refactors, small features with clear specs.
• •
  You can define "done" per task as a command (tests pass, linter clean).
• •
  You have reviewed enough single-agent work to calibrate trust (do pb-03 first).

Skip it for tasks that overlap in files, need mid-flight product judgment, or that you cannot specify without "you know what I mean".

Prerequisites

• •
  A terminal coding agent runnable per-directory, or a cloud coding agent (issue → PR).
• •
  Clean git state and fast deterministic tests (make test-fast under ~2 min — see pb-09; slow flaky tests make agents thrash).
• •
  Task specs written down, one per task, pb-02/pb-03 style.

The workflow

1. 1.

   Pick 3-4 non-overlapping tasks. Check independence at the file level: if two tasks plausibly touch app/models/order.py, serialize them. Good batch: (a) fix the pagination bug in /api/exports (repro attached), (b) add tests for services/pricing.py, (c) migrate utils/dates.py off the deprecated tz API.

2. 2.

   One worktree per task.

   Copy

   git worktree add ../wt-export-bug  -b agent/export-pagination
   git worktree add ../wt-pricing-tests -b agent/pricing-tests
   git worktree add ../wt-dates-tz    -b agent/dates-tz
   

   Worktrees share history but isolate working files — agents cannot trample each other, and each branch diffs cleanly against main.

3. 3.

   Launch each agent with spec + done-command + stop rule.

   Copy

   Task spec: [paste]. Definition of done: `make test-fast && make lint`
   both green, plus a new test reproducing the original bug.
   Commit in small steps with clear messages. If you are stuck for more
   than ~3 attempts on the same error, STOP and write BLOCKED.md
   explaining what you tried - do not thrash.
   

   Launch all, then go do something else. Resist supervising; the economics only work if launch is fire-and-forget.

4. 4.

   Morning review loop — triage first, review second. Per branch, in this order:

   Copy

   cd ../wt-export-bug
   git log --oneline main..HEAD     # sane progression?
   make test-fast && make lint      # rerun; never trust reported green
   git diff main --stat             # blast radius as expected?
   

   Then triage: merge-ready (full diff review now, as skeptically as a human PR — hallucinated APIs and weakened tests are the classic tells), salvage (right direction, needs one steering message — reply and relaunch), or discard (git worktree remove, branch deleted, spec improved for next time; a discarded branch that taught you the task was underspecified is not a loss).

5. 5.

   Merge serially, main stays green. Merge one, run the full suite on main, then the next — parallel development, serial integration.

6. 6.

   Tune the batch. Track your merge-ready rate weekly. Below ~50%, your specs are too vague or your tasks too entangled — fix that before adding a fourth agent.

Tool variants

• Terminal agents in worktrees (Claude Code et al.): the pattern above; per-worktree sessions in tmux panes or separate terminals.
• Cloud coding agents (Copilot coding agent, Codex cloud): assign issues instead of managing worktrees — isolation is theirs, review arrives as PRs; same triage loop on the PR list.
• Mixed: cloud agents for the mechanical tasks, one local terminal agent for the task you expect to steer.

Verification

• •
  Tests and lint rerun by you on every branch before review — agent-reported status is a claim, not evidence.
• •
  Each merged diff got a full human read; anything touching auth, payments, or migrations gets the same scrutiny as a stranger's PR.
• •
  git diff main --stat per branch matched the task's expected blast radius.
• •
  Full suite green on main after each serial merge.

Pitfalls

• Entangled tasks. File-overlap between branches turns morning review into merge-conflict archaeology. Independence is a launch-time responsibility.
• Reviewing four branches as a skim. Volume pressure erodes review depth exactly when provenance-aware review matters most. Cap batch size at what you can genuinely review.
• Salvage addiction. More than one steering round per branch and you have become a synchronous pair-programmer for four agents — discard and respec instead.
• Agents with production credentials or push access to main. Worktree agents get local repo access only; merging is a human act.

Restricted-environment variant

Parallel agentic work requires sanctioned agentic tooling; on client engagements that usually means Copilot coding agent under the client's GitHub Enterprise (issue → PR flow, firewalled), or agents running entirely inside the client's VDI/cloud tenancy. If only chat-level AI is sanctioned, keep the structure but drop autonomy: prepare the 3-4 specs in the evening, and run them yourself next day with AI-assisted implementation per task — the batching and spec discipline still pay. Local models are not yet reliable for unattended multi-hour agent runs; do not simulate this pattern on them for client deliverables.

Success criteria

• •
  3+ tasks progressed in one calendar day with under 2 hours of your total attention.
• •
  Merge-ready rate ≥50% and rising as specs improve.
• •
  Zero merge conflicts between agent branches (proof your independence check works).
• •
  Main never went red because of an agent merge.