Preventing two AI agents from editing the same files

Preventing two AI agents from editing the same files takes two layers: plan the work so that scopes do not overlap, and make shared writes conditional so that a stale update is refused instead of silently overwriting newer work. Planning catches most collisions before any agent runs. Conditional writes catch the ones that slip through in the records you control, such as task state and notes. Neither layer covers everything. An agent that writes directly to a file through its own tools is outside any coordination system you add, so the last line of defense is separate working trees and a merge step where conflicts become visible. This article goes through each layer and is explicit about where each one stops. For the wider problem of several agents sharing a project, including ordering and review load, see multi-agent project coordination.

Separate scopes before anything runs

Most collisions are visible in advance if each task declares its scope. Before starting a second agent, compare its scope with every task already in progress. If they share a file, either serialize the tasks with a dependency or redraw the scopes so they do not overlap.

Some files are shared by nature: dependency lockfiles, a central routing table, a migrations index, a changelog, a shared configuration module. Two agents adding a dependency at the same time will both rewrite the lockfile. Assign each hotspot to one task at a time, or keep edits to it out of agent tasks entirely and make them yourself at merge time.

Scope should be specific enough to compare. The checkout module and the discount rules might overlap; src/checkout/ and src/rules/discounts.py can actually be checked against each other. Ask the planning pass to list the files it expects to touch, and use that list.

Finally, limit how many write sessions run at once. Fewer concurrent tasks means fewer pairs to compare, and a WIP limit keeps that number honest.

Separate working trees

Even with clean scopes, agents running in the same checkout interfere. One agent's test run picks up the other's half-finished edit, a formatter run by one rewrites files the other has open, and a build directory is shared by both.

Give every write session its own Git worktree on its own branch. Edits then cannot meet until merge time, and at merge time Git shows any conflict explicitly instead of one change quietly replacing another. Merge one branch at a time, rebase the next onto the result, and rerun its checks before merging it. A rebase that conflicts is a sign that scopes overlapped after all, which is worth recording for next time.

Worktrees move the collision from a live race to a visible conflict. They do not remove the need for scope planning: two branches that both rewrite the same function will conflict, and resolving that well needs someone who understands both intents. If an agent resolves it, review the resolution as carefully as the original changes. See running several agent terminals for the day-to-day setup.

Refuse stale writes instead of overwriting

For records that several sessions update, such as task status, notes, a shared plan file or a database row, use revision checks. Each read returns a revision. Each write states the revision it was based on. If the record changed in between, the write is refused and the writer must read again and reapply its change. This is ordinary optimistic concurrency, and it turns a silent overwrite into a visible refusal.

BRAIN FLUID's concurrency tests show the behavior to expect: of two concurrent updates to the same card, one succeeds and the other is refused as stale [N10]. Retries need care too. An exact retry of a request that already succeeded should return the existing result rather than apply twice, and a changed request that reuses the same operation ID should be refused, because it is a different request presenting itself as a retry.

Apply the same idea to files where you can. A script that updates a generated file should check that the file has not changed since it last read it, and fail loudly if it has, rather than writing over someone else's edit.

The honest limit: direct file writes can still race

Revision checks only protect writes that go through the checking path. Coding agents edit files directly with their own tools. If two agents in the same working tree write the same file, nothing in between compares revisions, and the later write wins. The same testing that showed stale card updates being refused records this plainly: direct file writes by ordinary agent processes outside the mediated path can still race.

Hooks and command guards help but do not close the gap. They check the tool calls they can see against declared boundaries, and inspection of shell commands is necessarily heuristic, since a shell command can write files in ways a pattern does not recognize. They are useful guardrails, not an operating-system sandbox.

So the practical defense is layered. Plan scopes so overlaps are rare. Give each write session its own worktree so direct writes cannot meet. Use revision checks for shared records. Merge one branch at a time and review conflicts. And when an agent changes files outside its scope, treat it as a planning failure to fix, not just a diff to revert.

QUESTIONS

What happens when two AI agents edit the same file at the same time?

In a shared working tree, usually the later write wins and the earlier change is lost or mangled, often without any error. Each agent may then run tests against code the other half-wrote. In separate worktrees on separate branches, the edits do not meet until merge, where Git reports a conflict you can resolve deliberately.

Do Git worktrees stop AI agents from conflicting?

They stop live collisions in the working tree, because each agent edits its own checkout. They do not stop logical conflicts: two branches that change the same function will still conflict at merge, and two changes that are each fine alone can still break each other. Worktrees make conflicts visible and deliberate; scope planning makes them rare.

What is a stale write?

A stale write is an update based on an old version of a record. The writer read the record, someone else changed it, and the writer then saves its change as if nothing happened, overwriting the newer version. Revision checks prevent this by refusing any write whose base revision no longer matches the current one.

RELATED GUIDES

• What is a project management harness?

RELATED HARNESS PAGES

• multi-agent project coordination Multi-agent project coordination: keep Claude and Codex work on one project organized with shared cards, scope, authority and review.
• Running several AI agent terminals without losing track Running several AI agent terminals without losing track: one task per terminal, task-based names, a session ledger and a close-out check.
• WIP limits for AI agent work WIP limits for AI agent work: why agents make starting too easy, and why the limit belongs on review capacity rather than on running sessions.
• Why does my AI coding agent change files I didn't ask about? Unrequested edits come from missing scope, vague tasks, formatters and refactor drift. How to tell them apart, revert them and catch them next time.