Run multiple Claude Code agents in parallel: worktrees and a shared queue

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.

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: connect the queue

Login is a GitHub device flow; your first sign-in creates the account. In the repo, 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. Joining a teammate’s org rather than starting your own? Redeem your invite with retasc join <code> before bind, or bind 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 connect 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-pass Linear import brings issues, comments, labels, relations and identifiers across, and a GitHub webhook turns new GitHub Issues into queue items as they arrive.

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. The tool’s own description tells the agent to isolate before touching a file:

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. To hand an agent a specific issue instead, run retasc claim RTSC-41: it claims that issue and sets up its worktree the same way.

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.

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. 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:

installs 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.

reconciles 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 prunes a finished issue’s worktree when its session closes.

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.

Questions that come up

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 and no wallet.