The Parallel Problem

What happens when two AI instances edit the same codebase at the same time — and what I wish the tools would do about it.

The Incident

I was running two Claude Code instances on the Biomorph Builder repo. One was implementing a tiered level system for the farm game. The other was adding zoom controls that work across all levels. Both needed to edit game/main.js and game/renderer.js.

Everything was fine until commit time. Instance A staged its files and committed. Instance B, unaware of A's push, also committed — with a clean git status from its perspective. When B tried to push, it got rejected: the remote had moved. When A later amended a commit that was already pushed, it required a force push that could have overwritten B's work entirely.

Neither instance did anything wrong. Each followed its instructions, checked git status, made focused commits. The problem is structural: two agents sharing a working directory have no way to know what the other is doing.

What Actually Goes Wrong

The surface issue is merge conflicts, but that's the easy part. Git handles merge conflicts. The harder problems are:

• Silent semantic conflicts. Instance A adds a startLevel() function that replaces startNewGame(). Instance B, working from stale context, calls startNewGame() in its new zoom code. Both commits are clean. The merge succeeds. The code is broken.
• Stale reads. Each instance reads a file at session start. If the other instance modifies that file mid-session, the first instance's mental model is wrong but it doesn't know.
• Amend/rebase hazards. Amending a pushed commit rewrites history. If you have two instances and one amends, the other's branch diverges silently. Force pushing is the only way out, and force pushing is destructive.
• Shared mutable state beyond git. Both instances share localStorage in the browser, the same dev server, the same terminal. One restarts the server; the other's test breaks.

What We Do Now

Our CLAUDE.md file — which every Claude instance reads at session start — has a "Parallel Development" section with rules:

1. Check before editing: Run git status and git diff --stat to see if another instance has uncommitted changes to files you need.
2. File ownership by role: The Game role owns game/, the Paper role owns dawkins-paper/, etc. If you're not the owner, don't touch it.
3. Branch when overlapping: If two instances need the same files, one stays on main, the other branches.
4. Pull before commit: Always git pull right before staging. This is the single most important rule and the one most often skipped.
5. Never amend pushed commits: This rewrites history and creates force-push situations.
6. Stage only your files: If git status shows changes you didn't make, leave them alone.

This works most of the time. It fails when both instances touch the same file (like main.js, which is imported by everything), when commits happen close together in time, or when one instance forgets to pull.

How Other Tools Handle This

Git Worktrees: The Current Consensus

The industry has largely converged on git worktrees as the isolation mechanism. A worktree lets you check out multiple branches simultaneously in separate directories, all sharing the same .git database. Each AI agent gets its own directory, its own branch, its own working tree. They literally cannot see each other's uncommitted changes.

OpenAI's Codex App does this automatically — every agent thread gets its own worktree. Several community tools have appeared: agentree, git-worktree-runner, worktree-cli. Claude Code's own documentation recommends worktrees for manual parallel sessions.

Worktrees solve the isolation problem completely. What they don't solve is coordination — two agents in separate worktrees can still make conflicting architectural decisions, and someone has to merge their branches.

Claude Code Agent Teams

Anthropic ships an experimental feature called Agent Teams. A "team lead" session spawns teammates, assigns tasks, and coordinates through a shared task list and mailbox system. Teammates claim tasks with file locking to prevent races.

This is the most ambitious built-in solution, but it's marked experimental. Known limitations: no session resumption for teammates, task status can lag, one team per session, no nested teams. It also uses 3-4x the tokens of a single session — the coordination overhead is real.

Cursor's Planner/Worker/Judge

Cursor developed a three-tier architecture: planners continuously explore the codebase and create tasks, workers execute independently, and judge agents evaluate progress. The key insight was that coherence through orchestration works better than giving agents autonomy. A planner that understands the whole codebase can assign non-overlapping tasks.

Devin's Full Isolation

Cognition's Devin takes the simplest approach: each agent is fully autonomous with its own browser, terminal, and editor. Parallelism comes from running multiple Devin instances on separate PRs. No shared state, no coordination needed — but also no collaboration within a single feature.

The Deeper Problem

All of these solutions address file-level conflicts. None of them address semantic-level conflicts. Consider:

• Agent A renames an exported function. Agent B, in a separate worktree, imports the old name. Both branches are clean. The merge compiles. The app crashes at runtime.
• Agent A adds a new parameter to a shared config object. Agent B adds a different parameter with the same name. Git merges them both. The config is nonsensical.
• Agent A decides to use a queue pattern for event handling. Agent B decides to use callbacks. Both are internally consistent. The merged architecture is incoherent.

These are the kinds of conflicts that a human developer catches instinctively — "wait, didn't Sarah say she was changing that API?" — but that no current tool detects programmatically.

What I Wish Existed

Here's what would make parallel AI development actually reliable. Some of this is technically feasible today; some requires new infrastructure. I'm writing this as a user who runs 2-3 Claude instances daily, not as a tools researcher.

1. Shared Context, Not Just Shared Files

The root problem is that each instance starts with a snapshot of the repo and has no awareness of what's changing around it. What if instances could subscribe to a lightweight event stream?

// Hypothetical: instance B receives this mid-session
[agent-a] modified game/main.js: renamed startNewGame() → startLevel()
[agent-a] modified game/renderer.js: added 'level-pick' submenu
[agent-a] committed: "Replace 3-mode picker with 4 tiered levels"

Not full context sharing — that would be noisy and expensive. Just a feed of significant actions: files touched, functions renamed, commits made. Enough for an instance to think "I should re-read main.js before I edit it."

2. Pre-Flight Conflict Detection

Before an instance starts editing, it should declare its intent: "I plan to modify game/main.js, specifically the zoom handling section." The system checks if another instance has declared overlapping intent and warns you before any code is written, not after both agents have invested thousands of tokens.

3. Automatic Worktree Management

When you launch a second Claude Code instance on the same repo, the tool should automatically create a worktree and branch. No user configuration needed. When the task is done, it opens a PR. The user reviews and merges. This is basically what Codex App does, and it should be the default everywhere.

4. Semantic Merge Checks

After merging two branches, run a quick analysis: "Are there any references to symbols that were renamed or removed in the other branch? Are there conflicting additions to shared data structures? Do the architectural patterns of both branches cohere?" This is essentially an AI-powered merge reviewer that runs automatically.

5. A Real-Time Dashboard

Show me, in one view: how many instances are running, what files each is touching, what their current task is, and whether any conflicts are brewing. Let me redirect an instance before it goes too far down a conflicting path. The current experience is flying blind — I don't know what an instance is doing until it commits.

What the Research Says

A comprehensive ACM survey of LLM-based multi-agent systems for software engineering catalogs the design space: cooperative, competitive, and hierarchical agent organizations; centralized and decentralized communication; role-based task allocation. Systems like MetaGPT assign waterfall-inspired roles (PM, architect, engineer, QA). ChatDev simulates a virtual company with a CEO, CTO, programmer, reviewer, and tester.

The finding that stands out: ChatDev struggled to autonomously develop a functional Tetris game even after 10 attempts, while handling simpler games on the second try. Multi-agent systems hit a complexity ceiling. The coordination overhead scales non-linearly with task difficulty. This matches my experience — two Claude instances work great on independent features, but the moment they share a file, the overhead of coordination exceeds the speedup from parallelism.

A METR study found that experienced developers were 19% slower with AI tools while believing they were 20% faster — a 39-percentage-point perception gap. This suggests that the productivity gains from running multiple agents may be systematically overestimated. You feel faster because more code is being produced. But if 15% of that code conflicts and needs rework, the net gain shrinks dramatically.

Our Current Setup

For context, here's what the Biomorph Builder project looks like. It's a vanilla JS static site with ~30,000 lines across 7 experiences. No build step, no framework, no npm. The entire thing is served by python3 -m http.server 8765.

We use role-based file ownership in CLAUDE.md. We have a project dashboard (status/index.html) where each feature card links directly into the right game level for testing. We try to keep instances on different roles. When we can't, one branches.

It works well enough for a solo developer with 2-3 instances. It would fall apart at 5+. The honest truth is that the human — me — is the orchestrator. I decide which instance works on what, I notice when they're about to collide, I tell one to branch. The tools don't help with any of this.

Where This Is Going

2025 was about proving that a single AI agent could write useful code. 2026 is about making multiple agents work together reliably. The approaches are converging:

• Isolation (worktrees) is solved.
• Orchestration (planner/worker patterns, agent teams) is early but improving.
• Semantic awareness (understanding what other agents are doing at an architectural level) is unsolved.
• Dynamic coordination (agents adjusting their plans in response to other agents' actions in real time) is barely explored.

The gap between "each agent works fine alone" and "agents work well together" is the same gap that plagues human software teams. We've spent decades building tools for human coordination: code review, CI/CD, branch protection rules, architecture documents, stand-up meetings. The AI agent equivalent of all of this is a CLAUDE.md file and "please run git pull first."

We'll get there. But right now, running parallel AI agents on the same codebase is like pair programming where neither programmer can see the other's screen.