Dedicated machines over git worktrees
Why parallel agents got their own machines instead of shared worktrees.
I had a row of Claude Code sessions open in tmux panes — split windows in a terminal multiplexer, so I could watch several agents at once — each a coding agent (an AI that edits code on its own) working a different task in the same repo. I’d pointed them at git worktrees — git’s way of checking out several branches into separate folders from a single repository — because it looked like the clean way to run many agents in parallel without copying the whole repo.
Then the edits started disappearing.
What actually happened: agents sharing a tree fought over the git index — the staging area git locks while it stages your changes — and stepped on each other’s in-progress edits. Work an agent had just written was gone. “Worktrees ate my edits.”
The takeaway: give each parallel agent genuine isolation — a dedicated machine, or at minimum a fully isolated worktree on its own branch. Never a shared working directory. The moment nothing is shared, both failure modes vanish. Index contention goes away because there’s no shared lock to contend over; test interference goes away because no two agents touch the same working files at once.
I’ll own the wrong turn. I assumed the worktree boundary was enough isolation because the directories looked separate. It wasn’t — they still shared the underlying repo machinery, and the cheap version fails at the seam you can’t see.
Longer write-up: Git Worktrees Ate My Edits — Why We Switched to Dedicated Machines.
Still chewing on
- Where the crossover is: how many parallel agents justify a dedicated box — a whole separate machine — versus an isolated worktree.
- Whether merge-time conflict handling — sorting out clashes when two agents’ changes are merged — should re-dispatch the losing unit (re-run the agent whose changes lost the conflict) rather than hand-resolve it.