aq.dev / guides / why-parallel-claude-code-sessions-collide

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

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 short version for anyone already on worktrees: a worktree isolates files and nothing else. Ports, local domains, browser cookies, databases, caches, environment variables and running processes stay shared until you split them per task. The list below names each one, and the options table compares the tools that split them.

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.

CollisionWhat it looks likeFix
File collisionsTwo sessions edit the same working tree; the last write silently winsOne git worktree per session
Runtime collisionsDev servers fight over one port, migrations trample one database, builds overwrite one emulatorPer-session resources, then locks for true singletons
Landing collisionsParallel branches race to push and rebase against a moving mainSerialize the landing step

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.

What a worktree does not isolate

A worktree is a directory with its own branch and index. Everything a running app touches outside that directory is still shared by every session on the machine:

  • Ports and local domains. Every worktree inherits the same default port and the same local hostname, so the second dev server fails to bind or quietly serves the wrong checkout.
  • Browser cookies and OAuth redirects. Browsers scope cookies by host, not by port (RFC 6265, section 8.5), so localhost:4001 and localhost:4002 share one login session. OAuth providers redirect to the URL you registered, which is usually one fixed port.
  • Database state. A shared development database means shared rows, so one session's test data shows up in another session's assertions.
  • Seeds and migrations. Two branches with different migrations take turns rewriting one schema, and the migration table records a history neither branch has.
  • Caches. Redis keys, queue names, temp directories and build caches outside the worktree are shared unless you name them per task.
  • Environment variables and secrets. A .env file is usually gitignored, so a new worktree starts without one, and copying it gives every session the same keys and the same database URL.
  • Running processes. Dev servers, watchers and background jobs belong to the machine. Removing a worktree does not stop a process that was started inside it.
  • Preview access. Anything reachable at localhost is visible only on your machine, and a public tunnel exposes it to anyone holding the link.

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.

Options for isolating runtime state per task

Each option below isolates a different slice of runtime state, so most setups combine two or three. Vendor descriptions are as of November 16, 2026, from each project's own page.

OptionWhat it isolatesCreation costCleanupLimits
Plain git worktreeFiles, branch and indexA checkout plus a dependency installgit worktree remove; processes and databases stay behindPorts, databases, cookies, env and processes stay shared
Copy-on-write app clone (Laravel Herd 2 workspaces)A copy of the app on its own branch and its own domain; a copy of the database with --database=cloneHerd describes workspaces as copy-on-write clones "created in an instant"Managed by HerdSites that Herd serves (PHP and Laravel); the workspace demo runs on macOS; the announcement does not say whether workspaces need Herd Pro
Per-task container stack (Docker Compose with Postgres per task)Containers, networks, volumes and a Postgres per Compose project nameContainer start plus migrations and seedsdocker compose -p <task> down -vPublished host ports still collide unless each task picks its own; one database server per task costs memory
Per-worktree resource manager (Stanchion)A block of ten ports per lane, a copy of a template database (Postgres, MySQL or MariaDB, SQL Server, SQLite, or a custom command) and a per-lane .env.stanchionAs long as the template database takes to copystanchion down drops the copy, frees the ports and deletes the env file; stanchion gc tears down lanes whose worktree is goneAllocations are per repository; probing sees only ports bound right now; other up calls wait while a large copy runs; lanes reuse the same database login. First release 0.1.0 on November 6, 2026, with no adoption record yet
Named local URLs (Portless)A stable https://<name>.localhost per app and per linked worktree, a port from 4000 to 4999 through PORT, and a separate browser origin per nameOne local proxy; the first run creates a local certificate authority and may ask for sudoStop the app; the name is reused next runPre-1.0; needs Node.js 24 or later; trusts a local CA. Isolates the browser origin only, not databases, secrets or processes
Managed per-run Postgres (AlloyDB Express)A whole PostgreSQL instance per test or prototypeGoogle says a database is ready "in under two seconds"; it pauses when idle, and the overview says it resumes in about 20 secondsDelete the instance; idle compute is not billed, storage isPreview; PostgreSQL 18 only; 1 or 2 vCPU; storage up to 20 GB; no backups or SLA; a short list of regions. Check the AlloyDB pricing page for current rates
Database branching (Gnomon)A data branch inside one Postgres database: the rows and schema changes one run madeThe project says a branch "opens instantly and copies nothing"Discarded unless merged, per the project's SDKA new project; installed as an extension on PostgreSQL 15 to 18. Git migrations version schema intent, while a data branch holds what a run actually did to the data

A practical reading of the table: a worktree plus a per-task port and per-task database covers most web apps. Add named local URLs when two checkouts need separate logins in one browser, and a branchable or disposable database when agents run migrations you may want to throw away.

Check your own setup for runtime collisions

You can test any option above in under an hour with synthetic data. Use a small app with a login, a database and at least one migration, and record each result rather than assuming it.

  1. Create two worktrees of the same app on two branches. On branch B, add a migration that conflicts with branch A (for example, both add a column of the same name with different types) and a seed that writes different fake users.
  2. Start both dev servers. Note whether the second one fails to bind, takes another port on its own, or serves the first checkout's code.
  3. Log in on each in one browser profile as two different fake users. Reload the first tab and note which user it shows.
  4. Run the migration and seed in both worktrees. Inspect the schema and the users table from each app and note whose data each one sees.
  5. Restart one server and note whether it comes back on the same address, with the same session, against the same database.
  6. Tear down one worktree and list what is left: running processes, databases, containers, env files and ports still held.

Repeat the run with each option you are considering. Any step where the two worktrees see each other's port, session, rows or processes is a collision that option leaves in place.

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.

Runtime state in AQ, as of November 16, 2026

  • Files and setup. Every work item gets its own branch and git worktree, and AQ installs dependencies and runs the repository's setup command when it prepares the checkout (workspaces docs). On the Free plan this runs on your own Mac with the AQ Mac app; Pro adds a cloud machine (pricing).
  • Ports and previews. Each work item owns its own block of ten ports for its whole life, and a server on the first one is its live preview (Conductor migration guide). Live previews are on every plan; sharing, guest links and public preview links are Pro.
  • Secrets. Personal and organization secrets, optionally limited to one repository, reach terminals, previews, services and agent runs as environment variables and are replaced with their name in transcripts (secrets docs).
  • Databases. AQ does not create or branch databases. Point each work item at its own database with one of the options above, for example through a per-repository setup command.

Frequently asked questions

Do different localhost ports keep browser logins separate?

No. Browsers scope cookies by host, not by port, so localhost:4001 and localhost:4002 share cookies and one login can overwrite the other. Give each worktree its own hostname (for example a named .localhost address per worktree) or use separate browser profiles.

How do I give each parallel agent its own Postgres database?

Create one database per worktree from a template and pass its URL through DATABASE_URL. You can script CREATE DATABASE ... TEMPLATE yourself, use a per-worktree resource manager that does it on setup and drops it on teardown, run Postgres per task with Docker Compose, use a disposable managed instance per run, or branch the data inside one database. Pick by how large the database is and whether you need to keep what the agent changed.

Can two Claude Code sessions safely run in the same directory?

No. Both sessions read and write the same files with no locking, so the last write silently wins, and each agent ends up reasoning about a file state the other has already changed. The result is lost edits and spliced diffs neither session produced intentionally. Run each session in its own git worktree; as of August 2026 Claude Code can create one per session with its worktree flag.

Do git worktrees prevent all conflicts between parallel agents?

They prevent file conflicts completely: each session gets its own working directory, index, and branch, and git refuses to check the same branch out twice. They do nothing for shared runtime resources. Two worktrees still share your machine's ports, databases, and emulators, so a dev server or migration in one can still break a test run in the other. Isolate those per session too.

How do I stop parallel agents from fighting over port 3000?

Give each worktree its own port through an environment variable (PORT=4001 in one, PORT=4002 in the other) and check the convention into an env template so agents inherit it. Two processes cannot listen on one TCP port, and agents routinely misread the address-already-in-use error as a code bug, so preventing the collision beats letting the agent debug it.

What is the blackboard pattern for coordinating AI coding agents?

A shared file (usually markdown) listing tasks as claimed, in progress, or done, with one rule: a session must write a claim row before touching the work, and stale claims are reclaimed only after verifying real git state. It is a rediscovery of the classic blackboard pattern from distributed systems. It works well for one person's sessions on one machine; it does not help teammates who cannot see the file or the terminals behind it.

How do teams keep track of which agent session is doing what?

Solo developers use naming conventions, terminal tabs, and claim files, which stop working the moment a second person starts agents on the same repository. The team-shaped answer is shared visibility: a workspace list where every session, its task, its owner, and its live terminal are visible to the team. That is the layer AQ provides, with per-workspace worktree isolation underneath it and owner-managed privacy for work that should stay private.