10.2 Worktrees: Parallel Lanes, One Repo

Subagents parallelize thinking. To parallelize building in tracked files, one folder can only be one version of itself. Git worktrees provide multiple working copies on separate branches: isolated file lanes that still share repository and machine state.

What you will learn

• Understand what a worktree is and the collision problem it dissolves.
• Run two agent sessions with separate file lanes and documented shared-resource controls.
• Merge the lanes back: PRs as the integration seam.

Builder principle

Parallelism is bought with isolation. Worktrees isolate tracked files; you must isolate or coordinate everything else.

The collision problem, precisely

Say the site needs a gallery section and a booking form — independent jobs, ideal for parallel work. Run two sessions in the same folder and watch the mess bloom: Agent A's half-finished gallery is in Agent B's context (it reads the working tree — it now thinks the gallery is how things are); both write to index.html; the harness (9.3) fails on A's incomplete work while B is mid-edit, and both agents dive to "fix" it. Not a hypothetical — the standard first-attempt disaster.

Branches alone don't fix it: a branch changes what the one folder shows, and switching mid-work yanks the canvas out from under whichever agent was painting.

Worktrees: one repo, many folders

$ cd ~/builds/candle-site
$ git worktree add ../candle-site-gallery -b feature/gallery
$ git worktree add ../candle-site-booking -b feature/booking

Three folders now exist — the original on main, and two siblings, each a full checkout on its own branch, all sharing one underlying repository (same history, same remotes, no duplication of the .git innards):

~/builds/
├── candle-site/             ← main — YOUR lane: review + integration
├── candle-site-gallery/     ← Agent A's tracked-file lane
└── candle-site-booking/     ← Agent B's tracked-file lane

Worktrees prevent many same-folder edit collisions. They do not isolate ports, databases, caches, output outside the tree, cloud accounts, credentials, user-level settings/memory, or user-scoped MCP servers. Repository files such as CLAUDE.md and project Skills ride along; machine and user state may still be shared.

Before launch, assign each lane a unique port, test database/schema or tenant, cache/temp/output path, and least-privilege credential. Record shared resources explicitly. File isolation without environment isolation can make coherent worktrees change the same external state.

Running the lanes

One terminal per lane (terminal tabs are the orchestrator's dashboard):

# Tab 1                              # Tab 2
$ cd ~/builds/candle-site-gallery    $ cd ~/builds/candle-site-booking
$ claude                             $ claude

Brief each with the 5.6 scoped-task discipline — plus one new clause, the lane boundary:

You're on branch feature/gallery in a dedicated worktree.
Task: [full 2.3-grade brief for the gallery].
Stay in your lane: this feature only. If you find yourself wanting
to change shared files beyond [index.html's gallery region + new
assets], stop and tell me — that's an integration question.

Then you do what orchestrators do: rotate. Check tab 1, steer, hop to tab 2, review, back. The 5.5 session-shape rules apply per-lane; your own attention becomes the scheduled resource — which is 10.5's subject, and you'll feel why by the end of this exercise.

Merging: the integration seam

Lanes end at the same place: each agent commits, pushes, and opens a PR (gh from 8.4 — this is the moment that lesson told you to remember):

Commit your work, push the branch, and open a PR: what changed, why,
and evidence the harness passes.

Now integration is reviewing two PRs. Merge one, then update the second lane against current main using your team's merge/rebase workflow. Git surfaces overlapping text edits; it does not solve semantic conflicts, incompatible assumptions, shared migrations, or external-state collisions. Test the combined system.

Cleanup when a lane's merged:

$ git worktree remove ../candle-site-gallery

🌱 No-code lane⚙️ Engineer lane

Start with one build lane and one docs lane, but still assign distinct ports/temp paths and synthetic data. Let the agent propose Git commands; verify branch, paths, shared resources, and combined behavior before merging.

You possibly knew worktrees existed; agents are why they suddenly matter — the cost structure flipped. Worktree overhead used to buy your divided attention (bad trade); now it buys another worker's full attention (excellent trade). Practical notes: name worktrees by feature, keep them short-lived (lane rot is branch rot with a filesystem footprint), give dependency-installing stacks a per-worktree setup step (npm install per lane — or point CLAUDE.md at a bootstrap script so agents self-serve), and let CI + your 9.4 policy floor treat every lane identically. Three lanes ≈ a small team's WIP; your review capacity is now the constraint — instrument it like one.

Try it now

The two-lane drill, training-wheels version:

1. Two worktrees off your main project: feature/[real-small-feature] and docs/refresh; inventory shared resources and assign unique ports/temp/cache/data first.
2. Two terminals, two agents, two lane-bounded briefs (feature lane builds; docs lane updates your second brain — READMEs, decisions.md, log).
3. Rotate. Notice what your attention is doing — where it's needed, where it isn't. Take one journal note mid-flight.
4. Land both: PRs, reviewer subagent, harness green, you merge (docs lane first — it's conflict-free). Clean up the worktrees.
5. Journal the honest assessment: what did parallel cost you (attention, setup, integration) vs. what did it return? That ledger is the 10.5 conversation, pre-gamed.

Check your understanding

• Describe the collision problem's three failure modes in a shared folder.
• Why do worktrees suit agents so precisely — which Chapter 3 fact does it rest on?
• What's the lane-boundary clause, and what does it convert mid-flight collisions into?
• Why did the parallelism cost-benefit flip in the agent era?