Two topologies for parallel work
There are two ways to run several Claude Code agents on one backlog. The first is independent terminals: every agent is its own session that pulls one issue at a time. That setup, worktrees included, is covered in the parallel agents guide.
The second is one orchestrator session that plans, then fans the work out to subagents. You keep a single conversation with full context, and the subagents burn their tokens on execution instead of deliberation. One session decides, N sessions type. This guide is about that second topology, and about the queue call built for it.
What makes a wave safe to run
Handing five tasks to five subagents is only useful if none of the five depends on another. Pick the set by eye and you will eventually dispatch an issue together with the thing it blocks; one subagent then builds on code another is still writing.
The queue solves this in the eligibility rules. An issue is only eligible for dispatch while it is open, marked as agent work, and blocked by nothing, so any two eligible issues have no open dependency edge between them. A set drawn from the eligible frontier is mutually independent by construction, not by inspection. The server draws it in effective-priority order, where a blocker inherits the urgency of everything it gates, oldest first on ties.
When RTSC-51 lands, RTSC-52 becomes eligible and rides the next wave. The graph drains in dependency order without anyone scheduling it.
Peek, then claim
next_batch(n) has two modes, and only one of them locks anything. The default is a peek: the server returns the shortlist without claiming anything, so the orchestrator can look at the wave, drop what it doesn’t want, and decide how many subagents to spawn. Nothing is locked while you think.
Pass claim: true and the server claims the whole wave atomically. Every issue arrives with its own claim token and its own server-computed branch name, so no two runtimes ever disagree about where an issue’s work lands.
Single-agent pulls surface this too: next_issue attaches an advisory wave, explicitly labeled as available but not reserved, when more than one issue is ready. It is a hint to consider fanning out, not a lock.
The orchestrator loop
The working pattern is a loop, and it fits in one prompt to your orchestrator session:
Each subagent’s task brief is the claim response: the issue, its branch, and the standing rules: create the worktree before the first edit (git worktree add ../<repo>-rtsc-51 -b rtsc-51/dash-empty-states origin/main), stay inside it, checkpoint at milestones, and mark the issue done when the PR is up. The worktree rules and what happens when they are skipped are in the parallel agents guide.
Issues a subagent finishes are marked done; issues it could not finish are released with a handoff note (release_issue), which returns them to the pool with the checkpoint attached. Then the loop pulls again. An empty batch answers with counts of what is ready, blocked and claimed, so the orchestrator knows whether the backlog is drained or just gated.
The caps that keep a fleet honest
The session cap is the one that shapes real waves: a claimed batch is bounded by how much claim headroom the session has left, so one orchestrator can never lock the whole backlog away from other agents. When the cap is what shortened a wave, the response says so with cappedBySession, so you can tell “the queue is thin” from “I am holding too much.” Close or release what is done and the headroom comes back.
When a subagent dies mid-wave
Subagents inherit the same lease machinery as any agent: a claim lapses after 30 minutes without activity, a server-side sweeper returns it to the pool within five, and the next pull hands the issue out with its last checkpoint and a count of how many times it has been reclaimed. The rest of the wave keeps running; one dead subagent never poisons the batch.
For the orchestrator this makes failure boring. There is no bookkeeping to do: a lost issue simply reappears in a later wave, checkpoint attached, and any runtime can pick it up. The full lifecycle, heartbeats and fencing included, is covered in the parallel agents guide.
Sizing waves
The caps allow seven concurrent claims; that does not make seven the right number. Every subagent that finishes produces a PR, and PRs queue on one reviewer: you. Waves of three to five keep the review pile shallow enough that feedback still reaches the next wave. The other constraint is the backlog itself: waves work when issues are independent and well specified (the pile-of-bugs shape), and add nothing when one tangled epic is the actual work.
Sequence takes care of itself: eligibility is recomputed on every pull, so filing good dependency edges is the whole scheduling job, and the waves order themselves.
Questions that come up
How many subagents can work a wave at once?
next_batch returns up to 25 issues per call and defaults to five, and one session holds at most seven claims at a time, so a single orchestrator dispatches up to seven subagents concurrently. In practice three to five is the sweet spot: any more and waves return faster than you can review them.
What stops two subagents from touching the same task?
Each issue is claimed atomically with its own token, and each subagent works in its own git worktree, so neither the work nor the files are shared. The wave itself is also mutually independent by construction: an issue is only eligible while nothing open blocks it, so no issue in the set gates another.
What happens if a subagent dies mid-wave?
Its issue’s lease lapses, a server-side sweeper returns it to the pool within minutes, and the next pull hands it out with the last checkpoint attached, including a count of how many times it was reclaimed. The rest of the wave is unaffected.
Can a wave mix Claude Code with other runtimes?
Yes. The queue is a remote MCP server, so Codex, Cursor, OpenCode, Cline, Gemini and CI runners pull from the same backlog, and a checkpoint written by a Claude Code subagent can be resumed by any of them.
Wiring the queue into Claude Code takes three commands, covered on the connect page, with expected output in the docs quickstart. Signup seeds the first $10 of usage, so a first wave costs nothing to try.