Subagents and parallel worktrees

What it isCopy Anchor Link

A subagent is a worker the main agent starts for a focused job, such as searching a codebase or reviewing a diff. It has its own context window and returns only a summary, so the main conversation stays clean. A git worktree is a second checkout of the same repository on its own branch in its own folder.

Why it mattersCopy Anchor Link

Two agents editing the same checkout overwrite each other and test against each other's half-finished changes. Give each its own worktree and branch, then merge. Use read-only subagents freely for research since they cannot conflict. Use them to isolate noisy work: a subagent that reads fifty files and returns three lines saves your main context. Do not spawn agents for small steps, since each one carries startup cost.

A worked example: three jobs in parallelCopy Anchor Link

Job 1 (worktree A): add a search feature. Job 2 (worktree B): fix a login bug. Job 3 (read-only subagent): survey how errors are logged across the codebase. Jobs 1 and 2 cannot overwrite each other, job 3 returns ten lines. You review each result and merge one at a time.

When not toCopy Anchor Link

For a five-minute change, one session is simpler. Each agent adds startup cost and one more thing to review.

How the pieces fitCopy Anchor Link

When the main agent starts a subagent, it hands over a written task. The subagent works in its own fresh context, reads whatever it needs, and sends back a final message. Everything it read along the way is discarded from the main chat. If it read fifty files and replied with five lines, the main agent only carries the five lines.

A worktree is made with git, the version control tool. Both folders share one history but have separate files and branches. Changes in one do not appear in the other until you merge.

A second example: where it does not helpCopy Anchor Link

You ask three agents to refactor the same module, each in its own worktree. All three change the same functions. When you merge, you hit conflicts, and you must decide among three versions of the same code. Worktrees prevent overwriting, not overlapping work. Divide tasks so they touch different files. If two jobs need the same file, run them one after the other. Similarly, a subagent that must understand the whole conversation gains nothing, because its summary will lose context.

Trade-offsCopy Anchor Link

Parallel work saves your waiting time but adds review time, since you read several diffs. It also multiplies the cost, because each agent has its own usage. The summary a subagent returns can leave things out. If a decision depends on a detail, ask for it explicitly, or check the source yourself.

What goes wrongCopy Anchor Link

Merge conflicts, as above. A subagent that reports success without evidence. Forgotten worktrees that pile up on disk and old branches that confuse you later. To check a subagent's claim, ask which files it read and which command proved the result, then run that command. Clean up with the list command for worktrees and remove finished ones.

Try it yourselfCopy Anchor Link

In a repo you own, make a second worktree on a new branch, edit a file there, and look at the original folder.

1. Confirm the original file is unchanged.
2. Merge the branch.
3. Remove the extra worktree.

Expect the change to appear in your main folder only after the merge.

Common mistakeCopy Anchor Link

Running two agents in the same folder. Their half-finished edits collide and tests fail for confusing reasons.