How to stop two AI coding agents editing the same files

Use three layers, not one: claim the work before an agent starts, isolate each agent on its own branch and worktree, and check for overlap before anything merges. Worktrees alone only move the collision from edit time to merge time, and the worst collisions are ones git cannot see at all.

The worktree is the right first step, and we covered it in running Claude Code sessions in parallel. This post is about what it does not catch. The words used here, such as claim and git worktree, are defined in the glossary.

Why worktrees alone do not stop agent conflicts#

By the time git reports a conflict, both agents have finished and both branches pass their own tests. Someone now has to read two diffs, pick one, and throw away the other agent's afternoon. The conflict markers are the cheap part. The duplicated effort is the expensive part.

When you find out depends on the setup:

Setup	When you find out	What it costs
One shared checkout	While they edit	Tests failing on half-written files, mixed commits
A worktree per agent	At merge	Two finished branches, one to redo
Worktree plus a claim	Before editing	A note: that area is taken
Worktree, claim and overlap check	Before review	A rebase, not a rewrite

The aim is to move every collision as far up that table as you can.

Claim, isolate, check: how to keep agents out of each other's files#

Claim before editing. Before an agent changes code, it writes down the task, its owner, the branch, and the files or folders it expects to touch. Every other agent reads the claims first and picks something else if its work overlaps. Name the contract, not just the file: "changing what formatPrice takes" says more than "editing money.ts".

Isolate by task. One task, one branch, one worktree. Put the owner and the agent in the branch name, such as sam/codex/csv-export, so the branch list tells you whose work it is.

Check for overlap before merge. List the files each open branch touches, and ask git whether two of them merge cleanly:

bash

git fetch origin
# Every file touched by more than one open branch, and which branches
for b in priya/claude/token-refresh sam/codex/csv-export jo/cursor/settings; do
  git diff --name-only "origin/main...origin/$b" | sed "s|^|$b |"
done | awk '{ n[$NF]++; who[$NF] = who[$NF] " " $(NF-1) } END { for (f in n) if (n[f] > 1) print f ":" who[f] }'

# Will these two merge cleanly? Changes nothing on disk (Git 2.38 or later)
git merge-tree --write-tree origin/priya/claude/token-refresh origin/sam/codex/csv-export

Run it when a branch is opened, not when it is approved. A shared file found early is a conversation. Found late, it is a rewrite.

Some files collide so often that they need one owner: lockfiles, migrations, the file that registers routes, index files that re-export everything, and generated code. Name them in your instructions.

Semantic conflicts: the collision git cannot see#

Here is the one that gets through everything above.

Agent A, on feat/cents, changes formatPrice(amount) to take cents instead of whole units, and updates every caller it can find. Agent B, on feat/invoice-pdf, adds a new file that calls formatPrice(order.total) with whole units, the way the function worked when B started. The branches touch different files. Git merges them without a murmur. Both test suites passed. After the merge, every invoice shows 0.42 where it should show 42.00.

Nothing conflicted by line. It conflicted by meaning. Worktrees make this more likely, because each agent works against a snapshot that is already going stale.

Researchers have started to name the problem. A May 2026 paper on multi-agent collaboration with state management observes that giving each agent its own worktree defers conflict resolution to a merge step where recovery is expensive. So treat a green branch as news about the branch, not about the merge.

What catches it:

Land contract changes alone, and first. A change to a signature, a schema, a unit or an API shape is its own task. Merge it, then start the work that uses it.
Run the whole test suite on the merged result, not only on each branch.
Let the types carry the meaning. A Cents type, or an argument named amountInCents, turns a silent mismatch into a build error.

Agent instructions that prevent file conflicts#

Put this in CLAUDE.md, AGENTS.md, or whichever file your agents read at the start of every session:

## Working alongside other agents
- Before you edit anything, read TASKS.md. Pick a task nobody holds.
- Write your claim first: your name, the task, the branch, and the files
  or folders you expect to change.
- If a file you need is inside someone else's claim, do not edit it.
  Ask on their task, and do other work meanwhile.
- Never change a shared contract (a signature, an API shape, a schema,
  units) as a side effect. Make it its own task and say so.
- Do not touch lockfiles, migrations or the route table unless your
  task names them.
- Before a pull request: rebase on origin/main, run the full test suite,
  and list every file you changed.
- When you finish or stop, update or release your claim.

Is a task claim the same as a file lock?#

No. A claim is a statement of intent: it tells other agents what you are about to do so they can choose differently.

It is advisory. A claim does not stop a write. An agent that skips its instructions can still edit a claimed file, which is why the overlap check stays.

It expires. Sessions close and laptops sleep. A claim from yesterday should not block today, so let a person clear a stale one.

It is not a lock. File locks for agents fail in two ways. They deadlock, with an agent waiting on a lock its holder abandoned. And they give false comfort, because a lock on money.ts does nothing about a caller in a new file.

A claim in a markdown file has one more weakness: two agents can read "unclaimed" in the same minute. For one person starting sessions one at a time, that is fine. For several people, the claim has to be refused at the moment it is made.

When this is not enough#

Some work should not be split. A refactor that renames a concept across the codebase is one task for one agent; the others do unrelated work until it lands. If the parts need constant agreement, coordination costs more than it saves, as we wrote in how to split work between agents.

And the ceiling is people, not agents. Every branch needs a reviewer. Past about three agents per person, you start approving diffs you have not read.

Where Joxo fits#

When the agents belong to different people on different computers, a claims file is the weak point. Joxo keeps one task board for everyone's agents, whichever tool each person uses. When a second agent reaches for a task that is taken, it is told who already has it and picks other work. If an agent claims a task on files a teammate's agent is already changing, it is told which files and advised to wait or split the work, and both people get one short note. In Claude Code, the agent is also warned just before it edits such a file.

These are warnings, not locks, so the rule above and the check before merge still apply. A claim held by a computer that has gone quiet can be taken over, but only when a person agrees. Joxo is set up with one line pasted into each agent, and the FAQ covers what it can and cannot see. More in how to coordinate AI coding agents across a team, and for the review side, how to review pull requests from several coding agents.

Frequently asked questions#

Do git worktrees stop AI coding agents from conflicting?#

They stop agents overwriting each other's files while they work, which is worth having. They do not stop two agents doing the same task, and they do not stop changes that clash by meaning rather than by line. Those surface at merge time or later. Pair worktrees with a claim before work starts and an overlap check before review.

Should I lock files so only one agent can edit them?#

Usually not. Locks deadlock when an agent stops without releasing them, and they only protect the file they name, not the code that depends on it. A claim that names the task and the contract, plus a check for overlapping files before review, catches more and blocks less. Keep strict single ownership for a few hot files, such as lockfiles and migrations.

How many AI coding agents can work on one repository at once?#

The limit is review, not the repository. Each agent produces a branch that a person has to read, and reading does not speed up with more agents. Most people manage about three agents at a time. Beyond that, split the work across more people rather than more agents, and keep each task small enough to describe in two sentences.