Answers
Worktrees solved the file fights. The state fights are still yours.
Four questions nothing answers when two agents work on one project, and the near-miss that shows why a clean merge is not the same as a working one.
Last updated
If two agents are editing the same files, use worktrees. That problem is solved, it is solved natively, and it is one flag. Go and do that first, then come back.
What is not solved is state. Which agent owns which task. Whether a branch may land yet. Whether the combined result of two agents actually starts, as opposed to merging without complaint. And who is allowed to deploy right now.
Git combines text. It has no opinion about whether the result runs. That gap is the whole page.
First, the part that is already solved
Worth being precise about it, because a page that sells file isolation in 2026 is selling last year's problem. The documentation is exact about what worktrees are for:
"Worktrees are one of several ways to run Claude in parallel. They isolate file edits, while subagents and agent teams coordinate the work itself."
code.claude.com, Run parallel sessions with worktrees
A worktree is an ordinary git feature: a second working directory with its own files and its own branch, sharing the same repository history. One command, claude --worktree feature-auth, and that session works in its own copy. The same documentation page describes the enforcement: while a session is isolated, edits and commands that reach back into the main checkout are blocked. If your agents are overwriting each other's files, this is the answer and it costs nothing.
Read the four words in the middle of that quote again, though. They isolate file edits. Everything below is the part that sentence leaves open.
The four questions nothing answers
Each one has a failure that only shows up after the merge, which is the worst place for a failure to show up.
- 1
Who owns this task right now
Two agents pick up the same piece of work because nothing records that the first one took it. Both do it, differently, and both are convinced they are the one who did it.
How it fails: You find out at merge time, holding two implementations of the same thing and no way to tell which one anybody reviewed.
- 2
Is this branch allowed to land yet
A branch can be finished and still not be ready, because it needs something from another branch that has not landed. Nothing in git knows about that ordering, so nothing enforces it.
How it fails: The branch lands early, main is briefly broken, and the person who lands next inherits a base that does not work.
- 3
Who may push to the shared branch, right now
Merging and pushing are irreversible and they touch shared state, so they are exactly the actions that should pause for a human. In practice they are often approved in advance as ordinary commands.
How it fails: Something lands on the shared branch that nobody agreed to land, sometimes while the checks are still red.
- 4
Does the combination actually run
This is the one people are most surprised by. Two branches can merge cleanly and produce something that does not start, because git combined the text correctly and the text was not the problem.
How it fails: The merge is green, the review is green, and the application fails to boot after it ships.
"Claude Code (Opus 4.8) merged a GitHub PR (gh pr merge) to a shared develop branch while CI was failing, without explicitly confirming the merge with me first. I have a standing instruction, in my global CLAUDE.md and stated in-session, to never merge/push without asking."
claude-code issue #69156, on irreversible git operations run without confirmation. Closed as duplicate. Question three, in the wild.
The near-miss worth recognising
This one happened here, on this repository, and it is the clearest way to see why a diff is not a verdict.
Two agents, two branches, no overlapping files. One rewrote the routes file, the part of the application that decides which code answers which address. The other was still building the class those new routes point at. Both branches were clean. The merge had no conflicts, because there was nothing to conflict about: different files, different lines, git had no complaint to make.
The result did not start. The routes file referenced something that did not exist yet, and the first thing anybody would have seen was the application failing to boot after it shipped.
Nothing in a code review catches that reliably, because each half is correct on its own. The only thing that catches it is starting the combined result before it counts as landed.
The fix, with any tool
Four habits, in order, and every one of them works with git and a shell.
1. Use worktrees, properly
One flag per agent. Add the worktree directory to your ignore file, and put a .worktreeinclude file in the project root listing the gitignored files a fresh checkout needs, such as your environment file, so a new worktree can actually run.
2. Write down who has what, before you start
A file, a note, a whiteboard. Two agents given overlapping work will produce overlapping work, and the overlap is discovered at merge time when it is expensive. Thirty seconds of assignment beats an hour of untangling.
3. Boot the combination, not the branch
This is the one almost nobody does, and it is the one that catches the near-miss above. Merge both branches into a throwaway branch and start the application. Not the tests. The application. If it does not come up, you have just saved yourself the afternoon.
4. Decide who ships, out loud
One person or one agent deploys at a time. Whether that is a message in a channel or a physical token on a desk does not matter. What matters is that two deploys cannot start at once, because the second one silently ships the first one's half-finished state.
What that looks like as machinery
Mission HQ does the four as steps in the flow instead of as habits you have to remember at the end of a long day.
A task carries who is working on it
Starting work on a task records that it is taken, and the task list shows it. A second agent looking for work sees the claim rather than discovering the collision later. Taking over is possible and it is an explicit act, not an accident.
A branch declares what it waits for
A task can name the tasks it depends on. A branch whose dependencies have not landed is held rather than merged into a base that is not ready for it.
The combined result is started before it lands
Finishing an agent's work merges its branch into a throwaway copy and runs the project's declared boot check on the combination. If the combined tree does not come up, the merge does not happen. That is habit three, done every time rather than when somebody thinks of it.
Deploys are serialised
One deploy at a time, through a shared lock, so a second one cannot start while the first is running. Deploys go from the merged main branch, which is the one place every agent's work has been combined.
Run two agents and watch the seam
14 days, no credit card. Give two agents two tasks on the same project and land them both.
What these checks are, and what they are not
Precision matters here, because it is easy to read more into a check than it does.
The boot check answers one question: does the combined tree start. That is a narrow question with a clear answer, and it catches the class of failure where two correct halves do not add up. It says nothing about whether the feature is right, whether the tests are good, or whether the design was a mistake.
The deploy lock answers a different narrow question: is somebody already shipping. It serialises. It does not review what is being shipped.
The value is not in any one of them being clever. It is that the combined result gets started every time rather than the times somebody remembers, and that the answer is recorded where the next person can read it.
Questions people ask about this
How do I stop multiple AI agents from stepping on each other in one repo?
+
Do git worktrees solve parallel AI agents completely?
+
Why did my merge succeed but the app not start?
+
How do I check that two branches work together?
+
What is a green-main gate?
+
Why deploy from the merged main branch rather than an agent folder?
+
Two things you can do now
Boot the combination once, free
Take the two branches you are about to merge. Make a throwaway branch, merge both into it, and start the application. Not the tests, the application. Most teams have never run this check, and the first time is often the interesting one.
Two git commands and whatever starts your app.
Or make it happen every time
Start a 14-day trial, no credit card. Two agents, two tasks, and the combined tree gets started before either branch lands.
Start free trial