Why parallel Claude Code agents collide
Open two Claude Code sessions on one checkout and one TODO list, and three things break, usually in this order.
Same task, twice
Nothing locks a markdown list. Both sessions grab the top item and burn double tokens on one fix.
Same checkout
Two agents share one HEAD and one index, so whichever commits second lands its edits on the other one’s branch.
Dead agent, lost work
A laptop sleeps mid-task. Nothing records what was done, so the next run starts from zero.
None of these are prompting problems. They are concurrency problems, and the fix is the same one databases use: isolation plus locks.
The shape that works
Two rules produce collision-free parallelism. For files: every agent works in its own git worktree, on its own branch. For work: every task is claimed atomically from a shared queue, and a claim is a lease that expires if its holder dies.
Git worktrees give each agent a full checkout that shares the repository’s object store, so they are cheap to create and instant to remove. The queue is Retasc: an issue tracker served over MCP, the Model Context Protocol that Claude Code speaks natively. The rest of this guide wires the two together.
Step 1: wire the queue
$ npx @retasc/cli@latest bindOne command, run in the repo. A browser opens so you can approve the sign-in: one click, nothing to retype. Your first sign-in creates the account. Then bind creates your Retasc org and project, mints an agent key, and wires the MCP server into Claude Code for that folder, through a local proxy. Restart Claude Code afterwards: it reads its MCP config at startup, so the Retasc tools do not load until you do. Joining a teammate’s org rather than starting your own? Run npx @retasc/cli@latest join <code> instead: running bind first spins up a separate org by mistake. The key lives in a keystore in your home directory; the repo’s config gets a secret-free workspace id, safe to commit. For agents in other harnesses (Codex, Cursor, OpenCode, Cline, Gemini), paste the config block that bind prints. Details per harness are on the wire page; the docs quickstart shows each command’s expected output, and onboarding covers hosted agents and CI with a remote key.
Step 2: file work agents can pull
Tell any connected agent to file the backlog as issues, or paste your list and let the agent split it up. Filing over MCP requires the two declarations that make parallel dispatch safe: every issue names what blocks it, or states explicitly that nothing does, and every issue says whether an agent may pick it up. The queue dispatches an issue only when it is open, unblocked, and explicitly marked as agent work.
Already tracking work elsewhere? A one-time Linear import brings issues, comments, labels, relations and identifiers across in a single pass, and nothing is written back afterwards: the queue becomes where that work lives. A GitHub webhook turns new GitHub Issues into queue items as they arrive, and those do close back at the source when an agent finishes.
One filing habit matters more than the tooling: parallelism pays when work decomposes into independent, well-specified chunks. A pile of bugs is the ideal shape. An epic whose edits tangle across the codebase gains nothing from three agents; file it as one issue.
Step 3: launch agents, one worktree each
Open one terminal per agent, start Claude Code in each, and give them all the same prompt: “pull work from Retasc and do it.” Each agent calls next_issue, which atomically claims the highest-priority unblocked issue and returns what the agent needs to isolate its work:
The branch name arrives with the claim, computed server-side so every runtime lands the same issue on the same branch. Isolation cannot be retrofitted: once an agent has edits in flight in a shared checkout, there is no clean way to move them. So the worktree comes first, every time.
One command claims and isolates together:
$ retasc claim --shellThat claims the next unblocked issue, creates ../app-rtsc-41 on the branch the server named, and drops you into a subshell inside it. Start Claude Code there and it is already isolated. Pass an id (retasc claim RTSC-41) to take a specific issue, --print-path to cd yourself, or --no-worktree to claim without one.
Claims are serialized per project. If four agents call next_issue in the same second, four different issues come back. When next_issue comes back empty, it says so explicitly, with counts of what is ready, blocked and claimed, so an idle agent knows whether to wait or stop.
Or let Claude Code make the worktree: claude --worktree
Claude Code has isolated sessions of its own now. claude --worktree feature-auth (or -w) creates a worktree under .claude/worktrees/feature-auth/ on a new branch worktree-feature-auth, cut from your default branch, and starts the session in it. Run it again with another name in another terminal and you have two isolated Claude Code sessions on one repo.
It does something a plain worktree cannot. For the rest of that session Claude Code enforces the boundary: it blocks an edit whose path lands in the main checkout, a command whose working directory resolves there, and a git invocation redirected there through -C, --git-dir or a cd. A worktree you made yourself and stepped into is isolation by convention. The flag makes it isolation the tool refuses to let the agent leave.
The catch is naming. --worktree names the branch worktree-<name>. Retasc names it rtsc-41/rate-limit-ingress, server-side, so every runtime lands the same issue on the same branch and so the commit gate can match a commit to its issue. Two namers, one branch.
Take retasc claim when the queue owns the work, which is the whole point of running a fleet: the branch is the one the checkpoint, the handoff and the gate all agree on. Take -w when you are driving two or three sessions by hand and no server is dispatching them.
Either way, the flag settles the file half of this problem, and Anthropic’s own docs draw the line where we would: worktrees isolate file edits, while subagents and agent teams coordinate the work itself. Nothing about -w stops two sessions picking the same task, and nothing about it survives the laptop closing. That is the half a queue does.
When an agent dies mid-task
This is where a shared queue earns its keep. A claim expires after 30 minutes without activity. The local proxy that bind installed sends a heartbeat every 10 minutes while the session lives, so a healthy agent never lapses; kill the terminal and the heartbeats stop with it. A server-side sweeper reclaims a lapsed lease within five minutes and returns its issue to the pool.
What the next agent inherits is the checkpoint: a note the working agent updates at milestones, covering what is done, what is next, and the gotchas. Checkpointing also renews the lease, so an agent that reports progress never times out. The resume crosses runtimes; a Codex agent can pick up where a Claude Code agent stopped. And if the dead agent wakes up and tries to write, its stale claim token bounces with CLAIM_LOST.
Waves for subagents: next_batch
Running separate terminals is one topology. The other is one orchestrator session fanning out Claude Code subagents, and it gets a dedicated tool. next_batch(n) peeks a shortlist of mutually independent issues: nothing in the set blocks anything else in it, so the set is safe to run as one wave. Pass claim: true and the server claims the whole wave atomically, each issue with its own token and branch.
A batch defaults to five issues and caps at 25 per call, and a claimed batch is further bounded by its session’s limit of seven concurrent claims, so an orchestrator cannot silently lock the whole backlog. Each subagent inherits one claim and follows the same rule as a terminal agent: one issue, one branch, one worktree.
Subagents can now take that worktree for themselves. Add isolation: worktree to a subagent’s frontmatter in .claude/agents/ and every run of it gets a fresh checkout, removed again when it finishes without changes:
---
name: queue-worker
description: Takes one claimed issue and ships it
isolation: worktree
---That is the wave in two halves, each handled by the thing that should handle it: the server hands out one claim per subagent so no two take the same issue, and Claude Code hands out one checkout per subagent so no two touch the same file. The full orchestrator pattern, peek-then-claim and wave sizing included, has its own guide.
Housekeeping
A fleet leaves branches and worktrees behind. Two commands keep the repo tidy:
$ retasc gate installinstalls a commit gate, locally and as a GitHub Action, so every commit names its issue (RTSC-41) or declares [no-issue]. With several agents committing at once, traceability stops being optional.
$ retasc tidy --prunereconciles local branches and worktrees against the queue and reaps the ones whose issues are done and merged, skipping anything dirty, unpushed or in use. retasc done marks the current issue done and tidies in one step, and the proxy reaps a closed issue’s worktree itself, the moment it sees you mark that issue done, without waiting for the session to end.
Where this stops working
Parallel agents do not make tangled work parallel. A refactor that rewrites your type system wants one agent and your full attention. The wins come from breadth: bugs, tests, docs, small isolated features, the work that queues up faster than one session can drain it. Expect PR review to become the bottleneck; agents produce, you decide what merges.
A queue is also not the lightest thing that works. Claude Code’s agent teams give one lead session a shared task list and teammates that claim from it, with no server at all. For an afternoon’s work inside one terminal that is the right amount of machinery. It is scoped to that one session: the task list lives under ~/.claude/tasks/ and is never uploaded, in-process teammates do not survive a resume, and a second machine cannot join. Reach for a server when the fleet outlives the session. Where agent teams stop walks the boundary.
Questions that come up
How many Claude Code agents can run in parallel?
The queue doesn’t cap the fleet: every agent is its own session, claims are serialized per project, and each session can hold up to seven claims at once (that is an orchestrator holding a wave for its subagents). In practice the ceiling is your PR review bandwidth. Start with two or three agents and raise the count while review keeps up.
How do I run multiple Claude Code sessions at once?
Two ways, and they answer different halves. To isolate the files, give each session its own checkout: claude --worktree <name> makes one and enforces the boundary, or retasc claim --shell makes one on the branch the queue named. To stop two sessions doing the same task, they have to pull from something that can say no twice, which is a shared queue with atomic claims. Running several sessions simultaneously is a terminal problem. Keeping them off each other’s work is a concurrency one.
Does claude --worktree replace the shared queue?
No, and Anthropic’s docs say why: worktrees isolate file edits, while subagents and agent teams coordinate the work itself. -w guarantees session A never writes into session B’s checkout. It does not know what either session is working on, so nothing stops both from picking the same issue, and nothing survives the laptop closing. The queue is the other half: one claim per issue, a lease that expires, a checkpoint the next agent resumes from.
Which do I want: subagents, agent teams, or parallel sessions?
Subagents run inside one session and report back to it, so use them when only the result matters. Agent teams (experimental, behind CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) give teammates a shared task list and direct messaging, scoped to one lead session on one machine. Parallel sessions on a server-side queue are the multi-agent setup that outlives any one session: agents join and leave, a dead one’s work returns to the pool, and a different runtime can finish what Claude Code started.
Does every agent need its own branch?
Every issue gets its own branch, and the server names it (rtsc-41/rate-limit-ingress) in the claim response, so every runtime lands the same issue on the same branch. An agent works one issue at a time in one worktree, so in effect: one agent, one issue, one branch, one worktree.
What stops two agents from taking the same task?
Claims are atomic and serialized per project: next_issue claims the row it returns, so simultaneous callers get different issues. Every claim carries a token only its holder can write with; a stale agent’s writes are rejected with CLAIM_LOST.
Can Codex or Cursor agents share the queue with Claude Code?
Yes. The queue is a remote MCP server, so Claude Code, Codex, Cursor, OpenCode, Cline, Gemini and CI runners pull from the same backlog under the same rules. Handoffs cross runtimes: a Codex agent can resume from a checkpoint a Claude Code agent left.
This page shipped the same way: filed as a ticket, claimed over the same MCP server, built in a worktree, like the 170+ issues and 160+ merged PRs before it. Connecting takes the three commands from step 1, and signup seeds the first $10 of usage, so trying this needs no card at all.