Chapter 5 · Multi-Agent & Team Harnesses · Lesson 5.3

Worktrees & Parallel Isolation

The win: to run agents in parallel safely, give each its own isolated copy so they can't clobber each other's files.

The problem: one directory, two agents

Lesson 5.1 gave you the reason to run more than one agent at once: independent subtasks can go in parallel and finish sooner. But that speed-up only holds if the agents don't step on each other. If two agents share one working directory and both edit the same file at the same time, one write lands on top of the other and you get a corrupted, half-merged mess that neither agent intended. A shared working directory is the fastest way to turn parallel work into garbage. So before you parallelize, you have to isolate: each agent needs its own files to edit.

Git worktree: its own copy of the files

A git worktree is the plainest way to hand each agent its own files. It is a separate working directory, checked out on its own branch, but off the same repository. Agent A works in one worktree on branch agent/feature-x; agent B works in another on its own branch; neither can see or overwrite the other's edits. You create one with a single command:

git worktree add ../feature-x -b agent/feature-x

That makes a fresh folder at ../feature-x on a new branch, ready for an agent to work in. When the run is done, you merge that branch back and verify it, the same way you would review any diff. Per Simon Willison, Using Git with coding agents, worktrees are the natural fit for letting several agents run at once without a shared-directory collision.

Each parallel agent gets its own copy of the files. after Simon Willison, Using Git with coding agents

Sandboxes isolate the run, not just the files

A worktree keeps two agents from editing the same files. But an agent doesn't only edit files, it also runs code: builds, tests, scripts that touch the network or the disk. That is where a sandbox (from Lesson 3.3) comes in: an isolated environment that contains a whole run so it can't touch your real machine, and that is cheap enough to spin up many at once. The clean way to hold the two apart: a worktree isolates the files an agent edits; a sandbox isolates the whole run it executes. For real parallel work you often want both, each agent in its own worktree, inside its own sandbox.

Merge and verify after

Isolation is only half the deal. Parallel work pays off only if you can re-integrate it cleanly at the end, so treat the merge as its own step: merge each branch back and then run your eval set or tests (from Chapter 4) against the merged result, not against each piece in isolation. Two pieces that each passed alone can still break once combined. Each parallel worker here is a subagent (Lesson 1.5): it does its job in its own context and hands back a clean, condensed result, so the merge is the one place the pieces meet and get checked together.

Isolate before you parallelize

Check yourself

Two agents editing one shared directory will -

A shared working directory means two agents writing the same files at once, and one write lands on top of the other. That is corruption, not a speed-up. Isolate first: give each its own copy.

A git worktree gives each agent -

A worktree is a separate working directory on its own branch off the same repo, so each agent edits its own files. It is not a model, a shared branch, or a reviewer - you merge and verify the branches afterwards.

A worktree isolates files; a sandbox isolates -

A worktree separates the files an agent edits; a sandbox separates the whole run it executes, so builds and tests can't touch your real machine. For real parallel work you often want both.

Do this now (3 min)

In any git repo, hand yourself a second isolated copy of the files:

git worktree add ../try-parallel -b try/parallel

Edit a file inside ../try-parallel, then look at your original checkout, it is untouched. That is the whole point: an agent working in the worktree can't reach your main files. When you're done, clean it up:

git worktree remove ../try-parallel
I'm your teacher - ask freely. Want a worktree-plus-sandbox layout for running two or three agents at once, or a safe merge-and-verify routine for pulling their branches back together? Ask and we'll walk through it.

Go deeper

Primary source (read this): Simon Willison - Using Git with coding agents. The clearest guide to worktrees, branches, and keeping parallel agents from colliding.

Secondary: Addy Osmani - Agent Harness Engineering. Why sandboxes let you hand agents real execution power, many runs at once, without risking your machine.

Wisdom (test it on people): r/ClaudeAI - practitioners trading real worktree and parallel-agent setups for day-to-day work.

← 5.2 Orchestration patterns Course map Glossary Next: 5.4 The team harness →