Blog
Why parallel agent worktrees still collide at merge time
Separate worktrees do not guarantee a working merge. Reproduce an interface break, port collision and shared lock before running parallel agents.
By BringYourSubs4 min read
Parallel agent worktrees can merge without a Git conflict and still produce a broken application. Separate folders also do not isolate a shared development port or an application lock stored outside those folders. Plan integration and shared resources before launching concurrent writers.
We reproduced all three failure modes locally on 16 November 2026, using Git 2.34.1 and small Python fixtures. No coding agent, subscription request or production service was used. This is a practical follow-up to choosing apps on your Claude plan or ChatGPT plan, not a speed ranking.
What does a worktree actually isolate?
The Git worktree reference describes separate working trees attached to one repository, with per-worktree state such as the index. Anthropic's worktree guide describes separate files and branches while also documenting shared repository configuration and some permissions. Neither is a promise that arbitrary changes will work together.
Conductor's parallel-session guide uses a workspace as its independent task unit. If you use Conductor or T3 Code, ask a narrower question than whether the product supports parallel agents: which checkout does this task edit, and what outside that checkout can it change?
Our suggested resource sheet has four rows. Fill it in before the second writer starts.
| Resource | Example conflict | Suggested ownership |
|---|---|---|
| Code interface | A setting is renamed while another branch adds a consumer | Agree the interface, then integrate dependents |
| Network address | Two servers bind the same host and port | Allocate a distinct binding per running workspace |
| Shared generated output | Two generators target one external cache or output directory | Separate outputs or serialize the generator |
| Application lock | Two jobs create the same exclusive lock file | Give the resource one writer and a cleanup owner |
These are operating rules we propose, not settings that every app enforces automatically.
How can two passing branches produce a broken merge?
Our fixture starts with settings.py defining PAGE_SIZE = 20 and an old consumer importing that name. Both branches begin at the same commit.
Branch A renames the setting to BATCH_SIZE and removes the old consumer. Its check imports the new name successfully. Branch B leaves the setting unchanged and adds report.py, which imports PAGE_SIZE. Its check also passes against its own checkout.
We merge A into the integration branch, then B. Git reports success with exit code 0. Running the new report against the combined tree exits 1 with an ImportError: the report expects the old setting that A removed.
There is no same-file textual conflict between A's setting edit and B's new report. The Git merge reference explains how branch changes are combined; a successful merge is not our application acceptance test. This example deliberately separates patch integration from interface correctness.
To repeat the experiment in a disposable repository, create those two branches from one base, commit each change, and run each branch's check before merging. Then run the report again on the combined branch. Do not perform the demonstration in a working production checkout.
The fix is not to ask Git to choose a side. Update the report to use the agreed interface, review the intended behavior, and rerun the integrated checks. In our suggested workflow, A's owner announces the interface change before B writes a dependent consumer.
Why do ports and lockfiles collide across worktrees?
We bound a Python socket to loopback using an automatically allocated port, kept it open, then attempted a second bind to the same address and port without reuse options. The second bind raised OSError in this environment. Python's socket reference documents binding sockets and notes platform differences. A second checkout did not create a second network namespace.
For an application-lock demonstration, we created one file using exclusive creation, then tried the same operation again at the same absolute path. The second attempt raised FileExistsError. This is an application lock fixture, not a claim that separate worktrees normally share Git's per-worktree index lock.
Treat dependency lockfiles separately. If two branches change a tracked package lock, review their manifests and regenerate the integrated dependency state with the project's normal tooling. Do not resolve a generated-file conflict by accepting whichever side happens to be newer.
Our recommendation is one output directory per workspace where possible. When a resource must be shared, assign a single writer. Never delete a live lock merely because another agent wants to proceed; first identify its owner and whether its process is still running.
Which changes should run in sequence instead?
Queue changes when one task needs an interface another task has not settled. A schema migration and its consumers are a natural example. Parallelize independent exploration or tests while the interface decision is pending, then let dependent implementation follow the accepted contract.
A Hacker News maker discussion about Foremerge describes the same class of intent conflict: replacing an abstraction while another task extends it. That discussion is a motivation to inspect task scope, not independent proof of its product's performance claims. We have not tested Foremerge or adopted its reported results.
A short task brief can name the starting commit, files or symbols owned, interfaces that must stay stable, shared services and acceptance command. Add an integration owner. A promise not to edit the same file is insufficient when one task changes a contract consumed from another file.
What should you check before accepting parallel work?
Review each branch on its own, then test the exact combined revision. Record the integration order and keep the failing command when a combined check breaks. Repeat the resource sheet after changing a development server, database target or generation path.
Do not count an agent's completion message as an integrated result. Require the artifact, the diff and an acceptance command run against the actual merged tree. Preserve unrelated work before removing a worktree.
For account problems, use the login diagnosis guide. For an agent that loses the task during a long session, see context rot and reviewed handoffs. More capacity or a fresh conversation will not repair an incompatible code interface by itself.
Questions people ask
- Does Claude Code worktree isolation prevent every conflict?
- No. They isolate working files, not the compatibility of changes after integration or every host resource.
- Can Git merge cleanly while the application breaks?
- Yes. Our offline fixture merges two branches without a textual conflict, then fails because a newly added consumer imports a removed setting.
- Should every worktree use the same development port?
- Not when the processes share a host address. Assign distinct ports or separate network environments and verify the actual binding.
- Did BringYourSubs benchmark parallel agents?
- No. We ran deterministic local Git, Python socket and file-lock checks without any model requests. They show failure modes, not agent failure rates.
Sources
- git-worktree reference, Git project, 2026-11-16
- git-merge reference, Git project, 2026-11-16
- Run parallel sessions with worktrees, Anthropic, 2026-11-16
- Run multiple Claude Code sessions in parallel, Conductor, 2026-11-16
- socket networking reference, Python Software Foundation, 2026-11-16
- Discussion: Catch intent conflicts between parallel coding agents, Hacker News, naw103, 2026-11-16