Your Parallel Agents Are Overwriting Each Other's Work

Bottom Line

• File conflicts are the #1 killer of agent teams. Not prompt quality, not model choice.
• Partition by file, not by topic. Every agent gets an explicit, disjoint list of files it owns.
• ~5-6 tasks per agent is the workable size. More than that and the agent drifts outside its lane.
• Tell the lead to WAIT. By default it synthesizes before teammates finish and reports partial work as done.
• For real isolation, use git worktrees — one per agent, so they physically cannot collide.
• Clean up after runs: tmux kill-server and stale ~/.claude/teams/ folders accumulate.

What Actually Happens

The mechanism is unglamorous and it explains everything about the symptom.

An agent editing a file does roughly this: read the file, think for thirty to ninety seconds, write the file back. That write is based on the version it read at the start.

Now run two agents against the same file:

t=0    Agent A reads config.ts  (version 1)
t=2    Agent B reads config.ts  (version 1)
t=45   Agent A writes config.ts (version 1 + A's change)  ✓
t=70   Agent B writes config.ts (version 1 + B's change)  ← A's change is gone

Agent B did nothing wrong. It never saw A’s change, because A’s change did not exist when B read the file. Both agents report success. Both are telling the truth. One change silently no longer exists.

Nothing errors. There is no lock, no conflict marker, no warning. You find out later, usually when something that was definitely fixed is definitely broken again.

Fix One: Partition by File

The instinct is to split work by topic — “you do auth, you do billing, you do logging.” That fails, because topics overlap in files. Auth and billing both touch the user model. Logging touches everything.

Partition by file instead, and make the boundary explicit in each agent’s instructions:

You own exactly these files: src/auth/session.ts, src/auth/tokens.ts, tests/auth/session.test.ts

Do not edit any file outside this list. If your task appears to require editing a file you do not own, stop and report what you need and why. Do not edit it anyway.

That last sentence matters more than it looks. Without it, a helpful agent will fix the adjacent thing it noticed, and the adjacent thing is somebody else’s file.

Shared files — package.json, a barrel index.ts, a central types file, the router — should be owned by nobody during the parallel phase. Collect the required changes from each agent as a report, and apply them yourself in a single serial pass afterwards.

Fix Two: Right-Size the Tasks

Roughly five to six tasks per teammate is the sweet spot in practice.

Fewer than that and the coordination overhead is not worth the parallelism. Many more and the agent starts running out of context, loses track of its file list, and improvises — which is precisely when it wanders into somebody else’s territory.

Fix Three: Make the Lead Wait

A separate failure that looks like lost work but is not. The lead agent, by default, does not wait for its teammates. It will synthesize and report while two of them are still mid-edit.

The result reads like a finished summary of a completed job. It is a summary of whatever happened to be done at that moment. Nothing is lost, but you act on an incomplete picture, and the teammates’ later writes land after you have already moved on.

Say it explicitly:

Wait for every teammate to report completion before you synthesize anything. Do not summarize partial results. If a teammate has not reported, say so and wait.

While you are at it, pre-approve the common operations in your permission settings. A parallel run generates permission prompts multiplied by the number of agents, and answering forty prompts is a good way to approve one you should not have.

Fix Four: Worktrees, When It Matters

If the run is long, expensive, or touching code you care about, stop relying on instructions and enforce isolation physically. Give each agent its own git worktree:

git worktree add ../run-auth   -b agent/auth
git worktree add ../run-billing -b agent/billing

Each agent works in its own directory on its own branch. Collisions become merge conflicts at the end, which are visible, reviewable, and resolvable — instead of silent overwrites during, which are none of those things.

The cost is real: a worktree per agent means setup time and disk. Use it when the work mutates files in parallel and the loss would hurt. For read-only fan-out — search, analysis, review — you do not need it, because nothing is being written.

Cleanup

Team artifacts are not reliably torn down. After a few multi-agent sessions you accumulate orphaned tmux sessions and stale team folders:

tmux ls                    # see what's still running
tmux kill-server           # clear orphans
ls ~/.claude/teams/        # stale team folders pile up here

Harmless individually, worth clearing periodically.

The Principle

Agent teams are a distributed systems problem wearing a chat interface. Every hard-won rule about concurrent writers applies, with one thing missing: there is no lock manager and no conflict detection. The runtime will not tell you two agents raced.

So you cannot coordinate your way out of it at runtime. You have to make collisions impossible in advance — by partition, or by isolation. Assignment is the mechanism. Instructions are just how you communicate the assignment.

Related

• Your Agent Is Ignoring CLAUDE.md
• Why Claude Code’s Context Fills Up