Why Parallel Claude Code Sessions Collide, and What Actually Fixes It

Published August 19, 2026 · by the AQ team

Parallel Claude Code sessions collide because a standard development setup assumes exactly one developer: one working tree, one dev server on one port, one development database, one emulator. Run two or more agent sessions inside that setup and they fight over every one of those singletons, usually silently. The fix is not one trick but a ladder with four rungs: isolate files with git worktrees, give each session its own runtime resources (ports, databases), put a real coordination protocol in front of resources that genuinely cannot be duplicated, and keep a human able to see what every session is doing. This guide walks the ladder in order, with what each rung does and does not fix.

The three kinds of collision

People say "my sessions collided" about three different failures, and they have different fixes, which is why so much advice on this topic talks past itself.

File collisions: the lost update

The nastiest property of two agents sharing one working tree is that nothing errors. Each session reads a file, reasons about the version it read, and writes its edit back. Whichever write lands last simply replaces the other. A July 30, 2026 dev.to analysis of this failure ("Lost Update: when two AI agents edit one file, one silently wins") simulated it directly: with five agents writing to one file under worst-case interleaving, all five writes were acknowledged and only one contribution survived. Sampling fair random interleavings, roughly three quarters of two-agent runs lost data. No exception, no conflict marker, just work that vanishes.

It gets worse than lost text. The surviving file can be a chimera: half of one session's refactor spliced onto half of another's, a diff neither agent produced or ever saw. The agent then debugs code it believes it wrote, and burns your tokens chasing a regression that is really another session's edit.

Rung 1: one git worktree per session

Git already contains the fix for file collisions. A worktree is an additional working directory attached to the same repository, with its own checked-out branch and its own index. Git even enforces the discipline for you: it refuses to check the same branch out in two worktrees at once, precisely because two writers on one branch would leave one of them pointing at a stale state.

# one worktree per session, each on its own branch
git worktree add ../app-fix-auth -b fix-auth
git worktree add ../app-add-billing -b add-billing

# or let the harness create it (Claude Code, as of August 2026)
claude --worktree fix-auth

As of August 2026, Anthropic's own documentation recommends exactly this pattern for concurrent sessions, and Claude Code ships a worktree flag that creates the isolated checkout for you. Our git worktrees guide covers the mechanics (dependency installs, disk cost, cleanup), and the parallel sessions guide covers the workflow around it.

Worktrees end file collisions completely. What they do not touch is everything outside the filesystem, which is where the next round of collisions comes from.

Rung 2: per-session runtime resources

Two worktrees still share one operating system. The classic symptom is the second dev server dying with an address-already-in-use error because both worktrees default to port 3000: two processes cannot listen on the same TCP port, and an agent often misreads the port conflict as a broken build and starts fixing code that was never broken.

Databases fail the same way but more confusingly. Two sessions pointed at one development database will run migrations and seed data over each other, so tests fail for reasons that live in the other session's transcript. The rule that fixes both: anything a session mutates at runtime gets its own copy, wired through environment variables so each worktree resolves to different resources.

# each worktree gets its own port and its own database
PORT=4001 DATABASE_URL=postgres://localhost/app_fix_auth npm run dev
PORT=4002 DATABASE_URL=postgres://localhost/app_add_billing npm run dev

For SQLite it is even simpler: one database file per worktree. For Postgres, a database or schema per worktree. Put the convention in a checked-in env template so the agent inherits it instead of rediscovering port 3000.

Rung 3: a real protocol for true singletons

Some resources cannot be duplicated per session: a device emulator (a laptop runs only a couple), a staging environment, the landing step onto main. Here isolation is impossible and coordination is required, and through 2026 developers have been rediscovering classic distributed-systems tools on their laptops.

• The blackboard. An August 10, 2026 dev.to post ("I Built My AI Team a Blackboard") describes near-losing an active branch to a second session, then fixing it with a shared markdown file and one rule: a session must claim a task by writing a row before acting, and stale claims are reclaimed only after checking the real git state. The author later learned the pattern already had names (the blackboard pattern, stigmergy).
• Locks with leases. An August 4, 2026 post ("When Two Claude Agents Reach for the Same Emulator") documents two agents installing builds over each other on one emulator, each then debugging the other's app. The fix was a file-based lock with a fair queue, heartbeated leases so a crashed agent cannot hold the device forever, and fencing tokens so a stale holder cannot interfere after release.
• A merge queue for landing. A local merge queue for parallel Claude Code agents (open sourced July 2026) serializes the final integration step: branches land one at a time, each gated on the test suite, with crash-safe locking. That removes push races and rebase storms against a moving main.

The pattern behind all three: claim before acting, hold a lease not a lock, and serialize the one step that cannot be parallelized. If you are building this yourself, steal those three properties rather than the specific tool.

Rung 4: the collisions coordination cannot fix

Every mechanism above coordinates the agents. None of them helps the human juggling the sessions, and that is where the remaining failures live: forgetting which terminal holds which task, prompting the wrong session, closing a laptop on a half-finished run, or two sessions doing overlapping work because nobody could see both at once. The blackboard author's phrasing of the lesson: the real bottleneck was not compute but attention. We cover the ceiling this puts on one person in how many coding agents one developer can run.

Today that juggling is overwhelmingly a solo act. A July 2026 LeadDev analysis of 25,264 agent-generated pull requests across 2,361 popular GitHub repositories found that in 79 percent of agentic PRs the same developer both reviewed and modified the agent's contribution, and only about one in eight workflows involved multiple humans. A private blackboard file works for one person; it does nothing for the teammate who cannot see your terminal, does not know your worktree exists, and starts an agent on the same ticket.

Where AQ fits

AQ is the multiplayer coding harness where engineering teams run AI coding agents like Claude Code and Codex together: shared live terminals, a code editor, and app previews, in your own cloud. In this guide's terms, AQ builds the ladder in rather than asking you to script it.

Isolation is by construction: every workspace gets its own git worktree on its own branch (ai/{id}-{slug}), with dependencies installed automatically and a one-click rebase onto main, so file collisions between parallel tasks cannot happen. Each workspace gets its own live dev-server preview with a shareable link that teammates can view without an account, so previewing two tasks never means two servers fighting over one port. And the coordination layer that DIY setups keep reinventing as markdown files is simply the product surface: agents run as real CLIs in persistent tmux sessions on your team's VM, streamed live to the browser, so the workspace list is the blackboard. Everyone sees which tasks exist, who owns them, and what each session is doing right now, and sessions survive a closed laptop instead of dying mid-claim. Workspace owners choose visibility per workspace: team-visible, or private and shared with specific people. PRs are tracked per workspace, and Linear intake keeps task claims in the tracker instead of a file: label an issue ai-task, a workspace appears, and ownership follows the assignee.

Honestly stated: AQ does not solve every singleton. A device emulator or a shared staging environment still needs a lease protocol like the ones above. What AQ removes is the file, port, and visibility collisions, which for most web teams is nearly all of them. If you are one engineer with two worktrees and a port convention, the scripts above are enough. The gap AQ closes is when the second human shows up.