Claude Code subagents can work a claimed wave of issues

A Claude Code subagent starts with a fresh context

A Claude Code subagent runs inside a session with its own context window, system prompt, tool access and independent permissions, returning a summary to the main conversation. It starts with the task message, CLAUDE.md and git status, without your conversation history, invoked skills or files the parent already read. Put the issue description, relevant constraints and last checkpoint into the handoff instead of relying on what the parent discussed before spawning it.

Claude Code custom agents live in Markdown files under .claude/agents/ for a project or ~/.claude/agents/ for a user. Only name and description are required in frontmatter. Optional fields include tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort and isolation.

Definitions can also come from managed settings, plugins or the --agents JSON flag. A subagent inherits the parent’s built-in tools and MCP tools, with always-removed exceptions such as AskUserQuestion, while mcpServers adds servers for that subagent alone. The model resolves from the call, then frontmatter, then CLAUDE_CODE_SUBAGENT_MODEL, then the main conversation’s model, with model: inherit selecting the main model.

Anthropic’s changelog dates custom subagents to v1.0.60 on July 24, 2025. The Task tool became Agent in v2.1.63. Version v2.1.198, released July 1, 2026, removed the /agents wizard, so you ask Claude to create a subagent or edit its definition file directly.

Parallel subagents have separate contexts and optional worktrees

Since v2.1.198, Claude Code background subagents are the default in interactive sessions. Their results reach Claude as completion notifications in a later turn. Subagents run in the foreground in -p mode and the Agent SDK.

A session runs at most 20 subagents concurrently by default, with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS available to change that cap. Another spawn at the cap fails with Concurrent subagent limit reached. There is no total-count cap, while nesting reaches three layers below the main conversation.

For a Claude Code subagent worktree, set isolation: worktree in its frontmatter, which creates a temporary git worktree branched from the default branch. The worktree is removed if the subagent makes no changes, while Agent view and /batch also use worktree-isolated subagents. That default-branch starting point matters for queue work, where the claimed issue already has its own branch that the assigned subagent needs to use.

Each invocation creates a new instance, while SendMessage resumes an existing subagent by ID or name with its full conversation history. The built-in Explore and Plan subagents are one-shot. On an API error, a foreground Agent call returns partial output, while a background subagent is marked failed with its last output kept, as described in Anthropic’s subagent docs.

Skills reuse instructions while subagents isolate work

A skill is a SKILL.md file of instructions whose description stays in context so Claude knows it exists. Its full content loads into the main conversation when invoked. A skill with context: fork runs in a new subagent instead.

Anthropic’s split puts reusable prompts or workflows in skills when they should run in the main conversation. Subagents suit isolated work that returns a summary, keeping the delegated work’s conversation in the child’s context. A fresh subagent does not see the skills invoked in its parent’s conversation, so include any necessary instructions in its task message.

For work that needs to keep running in parallel or will exceed a context window, Anthropic points to separate sessions. A Retasc claim is one server transaction, so two agents in different sessions or MCP clients can never hold the same issue. The Dash lists every agent’s runtime, the issue it holds and the minutes left on its lease.

While agent teams are on, a named subagent launches as a teammate. With isolation: worktree, it still edits the main session’s working directory.

Codex starts subagents when you ask for them

Current Codex releases enable subagent workflows by default, while OpenAI’s documentation describes subagents without an agent-teams model. Codex starts them only after a direct request or an instruction in a project or skill. Enabled by default describes the availability of the workflow, so ask explicitly for parallel work when you want an orchestrator to delegate a wave.

The built-in agents are default, worker and explorer, while custom agents use TOML files under ~/.codex/agents/ or .codex/agents/. Subagents inherit the parent turn’s sandbox and approval settings.

agents.max_concurrent_threads_per_session caps concurrent Codex agent threads. OpenAI’s docs leave the default to Codex, while the source configuration sets it to 6. This cap describes concurrent threads in a session, so size the requested wave to the available threads as well as the number of issues ready to run.

Codex waits for all requested results before returning a consolidated response. Separately, the desktop app runs project chats in worktrees under $CODEX_HOME/worktrees, keeping the most recent 15 by default. That behavior isolates desktop chats, so establish each delegated issue’s worktree explicitly instead of assuming that a subagent invocation assigned it one.

A delegated task still needs a backlog claim

A parent gives a subagent a task to execute. Spawning that child does not claim a backlog issue for it. If several sessions read the same backlog, their task messages alone do not establish which session owns each issue.

Parallel edits can still collide when agents work on the same files. OpenAI documents no shared task list, claiming or locking across separate Codex agents or chats. Its long-running work guidance advises against having chats change the same files and points to worktrees.

Retasc supplies the work queue that agents pull from over MCP. It does not spawn subagents or read their definitions, while subagents reach the queue through the MCP server inherited from the session. Keep the responsibilities separate by having the orchestrator obtain claims before it gives the claimed work to children.

By default, next_batch peeks and reserves nothing. With claim set to true, the orchestrator claims the wave atomically. Claiming the wave before handing it to subagents keeps other agents from taking those issues while the leases stay active.

A claimed wave contains independent issues

The orchestrator calls next_batch for up to n issues, with a default of 5 and a maximum of 25. The response contains unblocked, unclaimed issues ordered by effective priority. Issues in a wave do not depend on each other, so subagents can work them at once.

By default, next_batch peeks without reserving anything. For a preview of 5 issues, use {"n":5} as the tool arguments before requesting a claimed wave with {"n":5,"claim":true} when the orchestrator is ready to dispatch work. Give subagents the issues returned by the claiming call, since a peek grants no ownership of the issues it shows.

Call next_batch with claim set to true to claim the wave atomically, receiving each issue’s own branch and claim token for the orchestrator to pass with that issue’s assignment to its subagent. A claim is one server transaction. Two agents can never hold the same issue.

A session can hold at most 7 claims, which prevents an orchestrator from reserving the whole backlog. A claimed wave reports that cap as sessionClaimCap. Match the wave to both the session’s remaining claims and the subagents it can run, rather than treating the batch maximum as available concurrency.

The orchestrator gives each claimed issue its own worktree

Run npx @retasc/cli@latest bind in the folder to connect it to Retasc. Setup asks for browser approval if you are not signed in. It gives the folder an agent key and wires the remote MCP server at https://mcp.retasc.com/mcp over streamable HTTP. Start or restart the agent in that folder. After next_batch with claim: true, the server tells the agent to create a git worktree for each claimed issue from that issue’s branch before the first edit.

Every claim through next_issue, claim_issue or next_batch hands over the issue’s last checkpoint. It records what is done, what is next and the gotchas, while next_issue also hands over the issue’s body. Have each subagent record a checkpoint as it works to preserve that handoff and renew its 30-minute lease.

When the work finishes, close the issue or send it to review. A review handoff must include a branch, PR or commit showing where the work is, unless a checkpoint already exists. Review is dispatched to a different person’s agent. The server refuses to let whoever sent work to review claim or accept that review. The orchestrator pulls the next wave.

Blocked work is never handed out. Close a blocker and its dependents join the queue. A blocker inherits the urgency of the work it holds up, so a chore blocking an urgent feature rises in the effective-priority order used for the next wave.

An expired lease leaves the checkpoint for the next agent

Your laptop can close while a subagent is working, or its process or terminal can be killed. If nothing renews its claim, the 30-minute lease lapses. The reclaimer returns the issue to the queue with its checkpoint intact. It stays in its owner’s lane, offered to the same person’s agents first. If nobody comes back for 7 days, it returns to the shared pool.

Heartbeats and checkpoints renew the lease. The Retasc CLI renews leases every 10 minutes without the model doing anything, so a long build keeps its claim.

The same person’s next agent can pick it up through the orchestrator’s next claimed wave. That agent resumes from the checkpoint on any runtime. The retasc claim command creates a git worktree on the issue’s own branch, with the worktree and the merged branch removed when you close the issue.

The next claimant receives the last checkpoint, its author, when it was written and the number of times the issue was reclaimed. Resuming a Claude Code subagent through SendMessage preserves that subagent’s conversation history, while reclaiming an issue hands a new claimant the checkpoint stored on the issue. Give the resumed issue its own subagent and worktree again, using the checkpoint as the task’s starting context even when the previous worker’s conversation is unavailable.

Questions about running a wave

Run the command in your repo folder to put the Claude Code orchestrator session and every subagent it spawns on the same work queue for AI coding agents. A new org gets $10 of usage at signup, with no card.