Run multiple Claude Code agents in parallel on one repo

Why parallel Claude Code agents collide

Open two Claude Code sessions on one checkout with one TODO list. Three failures usually follow in this order.

Changing the prompt does not fix these concurrency problems. The solution uses the same mechanisms as a database: isolation and locks.

Each agent needs a worktree and a claim

Two rules keep parallel agents from colliding. Give every agent its own git worktree and branch to isolate file edits. Have each agent claim tasks atomically from a shared queue, using a lease that expires if the agent stops.

Each git worktree is a full checkout backed by the repository’s shared object store. That makes worktrees cheap to create and instant to remove. Retasc supplies the queue through an issue tracker served over MCP, the Model Context Protocol that Claude Code speaks natively. This guide connects the worktrees to that queue.

Step 1: connect the queue

Run this command in the repo and approve the browser sign-in with one click. Your first sign-in creates the account. Then bind creates your Retasc org and project, mints an agent key, and connects Claude Code for that folder through a local proxy. The key stays in a keystore in your home directory, the repo gets a secret-free workspace id you can commit, and Claude Code needs a restart to load the tools because it reads MCP configuration at startup. To join a teammate’s org, start with npx @retasc/cli@latest join <code> instead: running bind first creates a separate org. Agents in Codex, Cursor, OpenCode, Gemini CLI, Grok or VS Code use the configuration block that bind prints, with per-harness details on the wire page, expected output for each command in the docs quickstart, and remote-key setup for hosted agents and CI in onboarding.

Step 2: file issues agents can claim

Ask a connected agent to file your backlog as issues, or paste a list for it to split up. Filing over MCP requires a dependency declaration, a true or false work flag, and a Conventional Commits changeType, so each issue names its blockers or explicitly declares that it has none. The queue dispatches only issues that are open, unblocked and marked as agent work. If a proposed issue resembles open work, creation is refused until the agent names the look-alikes it was shown, keeping agents that file their own backlog from creating duplicates.

A one-time import from Linear, Jira, ClickUp, Asana or Shortcut brings your existing issues, comments, labels, relations and identifiers across in one pass. It writes nothing back afterwards, so the queue becomes where you manage that work. GitHub or GitLab webhooks turn new source issues into queue items as they arrive. Each item waits for your sign-off before an agent can claim it, then closes the source issue when the agent finishes.

Parallel agents help when you can divide work into independent, well-specified issues. A backlog of bugs fits that pattern. An epic with edits tangled across the codebase gains nothing from three agents, so file it as one issue.

Step 3: start each agent in its own worktree

Open a terminal for each agent, start Claude Code, and give each session the same prompt: “pull work from Retasc and do it.” Each agent calls next_issue, which atomically claims the top unblocked issue by effective priority and returns the details needed to isolate its work. A blocker inherits the urgency of the work it gates, while deadlines set a minimum priority. Issues already in review outrank unstarted work, so next_issue directs an idle agent to review work before assigning something new.

The server computes the branch name and returns it with the claim, so every runtime uses the same branch for the same issue. Create the worktree before the first edit. Once agents have mixed their edits in a shared checkout, there is no clean way to move that work into separate worktrees.

This command claims an issue and creates its worktree:

The command claims the next unblocked issue, creates ../app-rtsc-41 on the server-named branch, and opens a subshell inside it. Start Claude Code there to work in the isolated checkout. Pass an id (retasc claim RTSC-41) to claim a specific issue, use --print-path to cd into the worktree yourself, or pass --no-worktree to claim without creating one.

Claims are serialized per project, so four agents calling next_issue in the same second receive four different issues when enough work is available. When next_issue returns no issue, it includes counts of ready, blocked and claimed work. An idle agent can use those counts to decide whether to wait or stop.

Let Claude Code create the worktree: claude --worktree

Claude Code can create an isolated session directly. Run claude --worktree feature-auth (or -w) to create .claude/worktrees/feature-auth/ on a new branch named worktree-feature-auth, starting from your default branch. The session starts inside that worktree. Run the command with another name in a second terminal to get two isolated sessions on the same repo.

For the rest of the session, Claude Code enforces the worktree boundary. It blocks edits targeting the main checkout, commands whose working directory resolves there, and git commands redirected there through -C, --git-dir or a cd. If you create a worktree yourself and start a session inside it, staying there depends on convention. With the flag, the tool blocks the agent from leaving that boundary.

The branch names differ. --worktree creates worktree-<name>, while Retasc computes a name such as rtsc-41/rate-limit-ingress on the server. Retasc uses that shared name to keep runtimes on the same issue branch and let the commit gate match commits to issues.

Use retasc claim when the queue dispatches work to your agents, so the branch matches what the checkpoint, handoff and commit gate expect. Use -w when you are managing two or three sessions yourself without a server dispatching their tasks.

The flag handles the file side of the problem. Anthropic’s docs make the same distinction: worktrees isolate file edits, while subagents and agent teams coordinate work. Two sessions using -w can still pick the same task, and the flag provides no queue to recover abandoned work when a laptop closes. A shared queue handles those cases.

When an agent stops mid-task

A claim expires after 30 minutes without a heartbeat or checkpoint. The local proxy that bind installs renews claims it has seen about every 10 minutes while the session runs. Closing the terminal stops those heartbeats, and a server-side sweeper reclaims a lapsed lease within five minutes, returning its issue to the queue. A remaining rtsc-NN/<slug> worktree without a live claim withholds the issue from dispatch for an hour.

The next agent receives the checkpoint, a note updated at milestones that records what is done, what comes next, and any gotchas. Each checkpoint renews the 30-minute lease, so progress reports keep the claim alive when they arrive before it expires. Resuming works across runtimes, so a Codex agent can continue where a Claude Code agent stopped. If the original agent wakes up and tries to write, its stale claim token is rejected with CLAIM_LOST.

Claim a batch for subagents: next_batch

You can also use one orchestrator session to distribute work to Claude Code subagents. next_batch(n) previews a shortlist of mutually independent issues, with no issue in the set blocking another, so you can dispatch them together. Pass claim: true to claim the whole batch atomically. Each issue receives its own token and branch.

A batch defaults to five issues and returns at most 25 per call. Claiming is also subject to the session’s limit of seven concurrent claims, which prevents one orchestrator from reserving the entire backlog. Each subagent receives one claim and follows the same rule as an agent in its own terminal: one issue, one branch, one worktree.

Claude Code can create the subagent’s worktree when it starts. Add isolation: worktree to the subagent’s frontmatter in .claude/agents/ to give each run a fresh checkout, which is removed when the run finishes without changes:

The server assigns a separate claim to each subagent, preventing two from taking the same issue. Claude Code gives each subagent a separate checkout, preventing them from editing the same copy of a file. The full orchestrator pattern, including previewing before claiming and choosing a batch size, has its own guide.

Link commits to issues and remove finished worktrees

Parallel agents leave branches and worktrees behind. Use these two commands to keep the repo tidy:

This installs a commit gate locally and as a GitHub Action, requiring every commit to name its issue (RTSC-41) or declare [no-issue]. That record lets you trace commits back to their work when several agents are committing at once.

This compares local branches and worktrees with the queue, removing those whose issues are done and merged while skipping anything dirty, unpushed or in use. retasc done marks the current issue done and runs cleanup in one step. The proxy also removes a closed issue’s worktree as soon as it sees you mark the issue done, without waiting for the session to end.

Where parallel agents stop helping

A refactor that rewrites your type system still needs one agent and your full attention because parallel sessions cannot make tangled work independent. The useful work to distribute is what accumulates faster than one session can finish it: bugs, tests, docs and small, isolated features. Expect PR review to become the bottleneck, since agents produce changes and you decide what merges. Claude Code’s agent teams use one lead session on one machine, as described in their own guide.

For an afternoon’s work inside one terminal, Claude Code’s agent teams give one lead session a shared task list and teammates that claim from it, without adding a server. The limits are local to that 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. Use a server when your agents need to keep working beyond that session. Where agent teams stop explains those limits.

Questions about parallel agents

This page was filed as a ticket, claimed over the MCP server and built in a worktree. We have shipped 1,030+ issues and 900+ merged PRs through that queue. The command from step 1 connects your repo, and signup includes $10 of usage with no card required.