Writing

Running Claude Code agents in parallel

2026-08-29

Why the first thing that breaks when you run several coding agents on one repo is the working directory, and what git worktrees fix about it.

The first time you run two coding agents on the same repository at once, they work. The second time, one of them stages the other's half-finished edit and commits it. Nothing warned you, because from git's point of view nothing unusual happened: two processes wrote to one working tree, and the last write won.

This is the problem you hit before any of the interesting ones. It has a boring fix.

One checkout is a shared mutable variable

A git repository has one working directory and one index. Every process that runs git add in it is writing to the same place. Agents make this worse than humans do, because they are fast and because they do not look up from what they are doing to notice that src/api.ts changed underneath them.

Concretely, what goes wrong:

Two agents edit different files, and one commits both sets of changes because git add -A does not know which edits were its own.
One agent runs git checkout to inspect another branch and silently moves the other agent's feet.
A test run started by one agent reads a file another is midway through writing, and fails for a reason that will never reproduce.

The last one is the expensive kind. It looks like a flaky test, so it gets retried, and the retry passes, so nobody investigates the actual cause.

Worktrees give each agent its own floor

git worktree creates a second working directory backed by the same object store. Each has its own checked-out branch, its own index, and its own files on disk. Commits land in one shared history, so nothing is fragmented, but no two agents share a filesystem.

git worktree add ../work/feature-a -b feature-a origin/main
git worktree add ../work/feature-b -b feature-b origin/main

Point one agent at each directory and the entire class of problem above stops existing. There is no coordination protocol to get right, no lockfile, no convention everyone has to remember. The isolation is structural.

Three things are worth knowing before you lean on this:

Put worktrees outside the repository. A worktree nested inside the checkout will be picked up by anything that walks the tree — build outputs, deploy staging, rsync. Keep them in a sibling directory.
Each worktree needs its own dependencies. node_modules is not shared, and a fresh worktree will fail with command-not-found until you install or symlink one.
Removing a worktree destroys uncommitted work. Remove it after the work is merged, not after it is written.

What is still hard

Isolation solves collision. It does not solve the two problems underneath it.

The first is merge pressure. Agents working in parallel produce branches that diverge from each other as fast as they diverge from main, and a branch that stops merging from the remote stops being work in progress and becomes a fork. Merging often is cheaper than resolving once at the end, and it is the kind of thing that has to be scheduled rather than remembered.

The second is attention. Ten isolated agents produce ten streams of output, and most of what they emit does not need you. The useful signal is narrow: which ones are blocked, which are waiting on a decision only a person can make, and which have quietly stopped. Reading ten terminals to find that out costs more than the parallelism saves.

That second problem is the one we build Maxxwell for — it runs a fleet of coding agents and brings back a single page of what actually needs a person. The worktree part, though, you can adopt this afternoon with nothing but git.