Parallel Agents, Separate Worktrees
Two agents in one working directory edit the same files and run the tests against each other's half-finished changes. A worktree gives each task its own directory and its own branch from one repository, so two agents can work at once without touching each other's files. Whether that is worth doing depends less on the agents than on how fast you read.
Parallel agents are the most tempting productivity claim in this field, and the easiest to get wrong. The git side is simple and this page covers it fully. The other side is a budget, and the budget is your attention.
What a Worktree Is
A worktree is a second working directory linked to the same repository, with its own checked-out branch, its own staging area and its own HEAD, while commits and branches are shared. In the words of the git documentation, the new worktree shares "everything except per-worktree files such as HEAD, index, etc." A commit made in one is visible from the other at once, because there is only one repository behind them.
Git also refuses, by default, to check out one branch in two worktrees at once. That refusal is exactly the protection two agents need: neither can start editing the branch the other is on.
$ git worktree add ../cragmoor-schedule -b schedule-date-calls main Preparing worktree (new branch 'schedule-date-calls') HEAD is now at 3473e53 Clarify the refund policy notes $ git worktree list …/cragmoor 2941125 [refund-window-12h] …/cragmoor-schedule 3473e53 [schedule-date-calls] $ git worktree add ../cragmoor-again refund-window-12h Preparing worktree (checking out 'refund-window-12h') fatal: 'refund-window-12h' is already used by worktree at '…/cragmoor'
$ git worktree remove ../cragmoor-schedule $ git worktree list …/cragmoor 4989e1b [refund-window-12h]
The transcript shows the whole life of a worktree. It is created next to the main directory with a new branch for the task. The list shows both directories and the branch each has checked out. The attempt to check out the refund branch a second time is refused, naming the directory that already has it. And when the schedule branch has merged, the worktree is removed and the list is back to one.
The Cragmoor Case
The refund change runs in the main directory, on its own branch. A second agent, in its own worktree, replaces the deprecated date calls in schedule that Chapter 7 found. The two tasks share no files, each has its own branch, and each diff is read on its own. Neither agent's test run sees the other's half-written code.
The order of reading still matters. The schedule diff came back first, because it was the smaller task, and waited while you finished the refund diff. That is the expected shape of parallel work: the agents finish when they finish, and the reviews happen one at a time, in the order you choose. Starting the second agent was worth it because the schedule task needed almost no review: a mechanical change with tests already in place.
What Worktrees Do Not Separate
A worktree separates tracked files and nothing else. Everything outside the repository directory is still shared: the local database, the ports a development server listens on, caches, packages installed for the whole machine, environment variables. Two test runs against one local database corrupt each other's data, and the failures look random, because they depend on which run wrote first.
Approval modes from Chapter 3 and the sandbox are set per session, not per worktree. A second agent gets whatever its own session allows, so set it up with the same care as the first.
The fix is to give each worktree its own copy of whatever it would otherwise share. A database name, a port and a cache directory set per worktree, through the environment or a local configuration file the worktree does not commit, let both test runs proceed without touching each other. Do it before starting the second agent; finding the collision through failures that look random costs more than setting it up.
When Parallel Pays
Parallel work pays for independent tasks, each well specified in the sense of Chapter 5, each slow for the agent and quick for you to review. Review is the bottleneck. Two agents produce two diffs, and your reading speed does not double. If review already takes longer than generation, a second agent adds a queue, not throughput, and the diffs wait while their branches drift away from the main line.
The arithmetic is simple. If a diff takes the agent fifteen minutes to produce and you an hour to review, one agent already keeps you busy, and a second one doubles the queue without changing what merges in a day. If a diff takes an hour to produce and ten minutes to review, you are idle most of the time, and a second agent on an independent task nearly doubles what you merge.
When It Does Not
It does not pay for tasks that touch the same files, which conflict when they merge. It does not pay for a task that needs the other's result, which can only wait. It does not pay for exploratory work you need to watch. And running two agents on the same task to keep the better answer costs two full reviews for one merge, because choosing the better diff means reading both.
Cleaning Up
Remove the worktree when its branch merges. A forgotten worktree keeps its branch checked out, and git will then refuse to check that branch out anywhere else, which shows up weeks later as a puzzling error in a directory nobody remembers making.
A branch is a line of history, and one directory shows one branch at a time. Switch branches when you work on one thing at a time.
A worktree is an extra directory showing another branch of the same repository. Use it to run two tasks side by side.
A clone is a separate repository with its own copy of history. Use it when the work must not share branches or commits with yours until it is pushed.
- "Two agents means twice the output." It means twice the diffs. Output is what you merge, and merging waits on reading.
- "Separate branches in one directory are enough." One directory shows one branch at a time, and switching under a running agent changes the files it is editing.
- "Worktrees isolate everything." They isolate tracked files. The database, the ports and the environment are still shared.
- "Cloning the repository twice is the same thing." It works, with two copies of history whose branches do not see each other until pushed. Worktrees share one repository, so a commit in one is visible from the other at once.
- "Parallel agents are a technique for large teams." They rest on a git feature and a reading budget. The limit is the reviewer, not the size of the team.
- Give each parallel task its own worktree and its own branch, both named for the task.
- Start a second agent only when your review queue is empty. Review is the bottleneck, not generation.
- Separate shared resources per worktree, such as a database name or a port, before running tests in both.
- Remove a worktree as soon as its branch merges.
Knowledge Check
Two agents work in two worktrees of the Cragmoor repository. What does each worktree keep for itself?
- Its own files, staging area and HEAD, while commits are shared
- Its own copy of the history, which it shares when it is pushed
- Its own local database, ports and environment for running tests
- Its own approval mode, set automatically when the worktree is added
Both agents run their tests at the same time against one local development database. What do you expect?
- Nothing unusual, since each worktree has its own copy of the data
- Git blocks the second test run until the first one has finished
- Failures that look random, as each run changes the other's data
- Slower tests that otherwise pass, because the database is busier
Reviewing a diff takes you about an hour, and the agent produces one in fifteen minutes. What does starting a second agent add?
- Twice the merged changes per day, since generation doubles
- A growing queue of unread diffs, not more merged changes
- Faster reviews, because each agent checks the other's work
- Shorter sessions for both, so each diff becomes smaller to read
A colleague wants an agent to work on your branch's code without ever touching your branches or commits until it pushes. Worktree or clone?
- A worktree, because it keeps a separate copy of the history
- Neither: a second branch in your own directory is enough here
- A worktree, because its commits stay hidden until it is pushed
- A clone, because its history stays separate until it is pushed
You got correct