Claude Code Subagents: A Practical Parallel Guide

Key takeaways

• Claude Code subagents are scoped agent definitions with their own prompt, tool restrictions, and isolated context window, spawned for tasks with clear acceptance criteria.
• Use subagents for tightly coupled work in one repo and agent teams or parallel sessions for independent tickets across repos.
• Restrict each subagent's tool set to the minimum and put concrete acceptance criteria in the system prompt, not in per-run prompts.
• Give every parallel subagent its own git worktree and branch, and only parallelize tasks with disjoint file ownership.
• Keep subagent chains to two or three steps with verifiable handoffs, because a botched first step poisons every queued prompt behind it.

Claude Code subagents are scoped agent definitions that run tasks in isolated context windows, so you can dispatch refactors, reviews, and test runs in parallel instead of babysitting one session. This guide gives you a decision framework for subagents vs agent teams, copy-ready subagent configurations, and parallel orchestration patterns with the failure modes practitioners actually hit.

What are Claude Code subagents and when should you use them?

A subagent is a separate Claude instance you define in a Markdown file with its own prompt, its own tool restrictions, and its own context window. The main loop spawns it for a scoped task, gets the result back, and keeps its own context clean. Anthropic documents the definition format and tool settings in the official Claude Code subagents docs.

Subagent vs a second terminal

A second terminal is you juggling sessions: you queue the next prompt, you paste context, you review each diff. A subagent runs inside one session, so the main agent coordinates instead of you. If you already run parallel agents across repos, the same scoping logic applies at the orchestration layer, which is what we cover in our guide to parallel coding agents.

When a subagent is the wrong tool

Subagents pay off when a task is well-scoped, has clear acceptance criteria, and produces output the main loop can verify. They are the wrong tool for exploratory work where you and the model need to think together, or for anything where a wrong first step poisons every prompt after it. When you find yourself writing a definition longer than the task, do it in the main loop instead.

Claude Code agent teams vs subagents: which fits your workflow?

Subagents run inside one session and share the lead agent's context. Agent teams are separate sessions with their own context, coordinating through a shared task list. The choice comes down to coupling: tightly coupled work on one codebase favors subagents, independent parallel work favors a team or a fleet of sessions.

The three-question decision test

1. Do the tasks share files or state? Same branch, same modules: subagents. Separate tickets in separate repos: separate agents.
2. Does each task need full context, or a slice? A slice (write tests, review a diff) is a subagent. A whole feature is its own agent.
3. How much supervision can you afford? Subagents cost one review pass at the end. Parallel agents each need their own diff review, so budget your review time before you budget your agent count.

	Subagents	Agent teams / parallel sessions
Context	Shared with lead	Isolated per agent
Best for	Coupled tasks, one repo	Independent tickets, multi-repo
Your overhead	One final review	Review every diff (how to review agent PRs)

Where each model breaks down

Subagents degrade when the lead's context fills and handoffs lose detail. Teams break when tasks were never independent: two agents editing the same module produce conflicts you resolve by hand. If you cannot write acceptance criteria sharp enough that a stranger could verify the work, neither model saves you; the task needs re-scoping first.

Which subagents belong on a best-of list for real projects?

Most teams only need four or five subagent types running repeatedly. Below are the configurations worth copying, grouped by the job they do. If you want the broader landscape before committing to a setup, this comparison of cloud coding agents covers how orchestration layers differ.

Code review and verification subagents

A reviewer subagent reads the diff against your acceptance criteria and reports pass/fail per criterion, not prose. A second verifier subagent runs the test suite and linters, then returns only failures with file paths. Anthropic's engineering writeup on multi-agent systems found the orchestrator-worker pattern works best when workers have narrow, verifiable jobs (source). Keep each reviewer scoped to one concern: correctness, security, or style. One agent judging everything produces mush.

Planning and scoping subagents

The scoping subagent is the highest-leverage one you can write. It takes a Linear issue and returns a task brief: files to touch, constraints, done conditions, and what not to do. This matters because the failure most teams hit is not the model messing up a refactor, it is the next prompts in the queue inheriting that mess. A scoping subagent that produces a written, checkable brief fixes the "I was the glue between every step" problem: the plan exists as an artifact, so when something goes wrong you have a record of where. It also stops you from hand-writing the same context block into six terminals. Write the brief format once, and every parallel agent starts from the same contract instead of your paraphrased mood that morning.

Repo hygiene and migration subagents

A migration subagent handles mechanical, wide-diff work: dependency bumps, codemods, renaming an API across repos. Scope it to one repo and one transformation, and pair it with the verifier so a broken step halts the queue instead of propagating. A hygiene subagent audits for dead code, stale docs, and TODO debt on a schedule. These are low-glory jobs, but they are exactly what parallel agents absorb well while you review the diffs that actually need judgment.

How do you write a subagent definition that stays on target?

A subagent definition is four decisions: the system prompt, the tool list, the model, and the scope boundary. Write all four down or the agent improvises them. A weak definition produces an agent that "helpfully" edits files you never asked it to touch.

Restricting tools on purpose

Give each subagent the minimum tool set. A reviewer agent needs Read and Grep, not Edit or Bash. A test-runner needs Bash scoped to your test command, not unrestricted shell access. Tool restrictions are the cheapest guardrail you get: a subagent that cannot write cannot silently break a sibling agent's worktree.

Acceptance criteria in the system prompt

Put the definition of done in the system prompt, not in the prompt you type each run. "The migration is complete when pnpm test passes and no raw SQL strings remain outside db/" beats "do the migration carefully." Concrete criteria let you review the diff against a checklist instead of vibes, and they survive handoffs between agents. For prompt patterns that hold up across a queue of tasks, see https://aerunit.ai/fr/stories-for-coding-agents.

The honest gap: a well-written definition still fails when the underlying model picks the wrong model tier for the job. Opus for architecture decisions, Sonnet or Haiku for mechanical sweeps. Match the model to the task in the definition itself, and revisit that choice when a subagent starts burning tokens without moving the diff forward.

How do you run Claude Code subagents in parallel safely?

Git worktrees as isolation

Each parallel subagent needs its own checkout. Git worktrees give every agent a separate directory on a separate branch, so two agents editing the same repo never stomp on each other's files. Anthropic's docs recommend exactly this for running multiple Claude Code sessions in parallel, with each session pinned to its own worktree. One worktree per Linear ticket, one branch per worktree, and the diff is your review unit.

Sequencing vs true parallelism

Not every task deserves its own worktree. Parallelize only tasks with disjoint file ownership: one agent on the API layer, another on the frontend, a third on migrations. If two tasks touch the same module, queue them sequentially instead, or you will spend your afternoon resolving merge conflicts that neither agent could see.

For tasks that are genuinely independent, a queue that assigns work as worktrees free up keeps agents busy without you pasting the next prompt by hand. Aerunit handles that assignment across repos, and its instant feedback loop surfaces a failed diff before the next queued task inherits the mistake. Merge strategy stays simple: fast-forward or squash per branch, review the diff, then merge.

What are common subagent failure modes and how do you avoid them?

Context degradation in chained subagents

If a subagent botches step one of a multi-step refactor, every queued prompt inherits the damage. The fix is to make each subagent's handoff verifiable: require a diff, a passing test, or a written summary in the task output before the next agent starts. Keep chains short, two or three steps, and route anything ambiguous back to you instead of the queue.

Knowing when the work is actually done

An agent saying "done" is not completion. Define acceptance criteria in the subagent definition itself, and make the agent prove them: tests green, build clean, diff reviewed by you. If you cannot state what "done" means for a task, do not queue it.

Polling token burn

Watching six terminals or re-prompting to check status burns tokens and your attention. Batch your check-ins: review diffs on a schedule, not continuously. The bottleneck is rarely the agent; it is the routine around it, so design the routine to be sparse and repeatable.

Where can you find working subagent examples on GitHub?

Anthropic's own examples repo and community collections give you starting definitions, but most are demos, not battle-tested configs. Treat any repo as a candidate, not a solution.

What makes an example worth copying

Check three things before you paste a definition into .claude/agents/. First, does it pin scope: a bounded file set, explicit acceptance criteria, and a named output format. Second, does it say what the subagent must not touch, since configs that only describe the happy path fail in real repos. Third, does the author show it running on anything beyond a toy codebase.

The practitioner write-ups matter more than star counts. One builder documented how a small refactoring error in step one poisons every queued prompt behind it (source). Copy examples that acknowledge that failure mode, not just the ones that look clean.

How do subagents fit a Linear-driven parallel agent workflow?

From ticket to subagent handoff

Each Linear ticket becomes the subagent's prompt: the acceptance criteria in the description are the definition of done, and the branch name comes from the ticket ID. You queue the next ticket instead of queueing the next prompt, so agents stay busy while you review the diff from the last run. The failure mode from earlier sections still applies: if a subagent misunderstands the file structure, every queued ticket inherits the mistake, so keep a human checkpoint between the first run and the rest of the queue.

Where orchestration tooling takes over

Past three or four parallel agents, you are the glue again: polling status, pasting context, tracking which worktree holds which run. That is the gap Aerunit targets. It watches your Linear queue and dispatches tickets to Cursor Cloud Agents with cross-repo awareness, billing through a shared team credit pool. The honest caveat: it assumes Linear plus Cursor Cloud Agents, so if your subagents run locally in Claude Code, you still need the worktree discipline from the parallel-safety section.

FAQ

Do Claude Code subagents share context with the main agent?

No. Each subagent runs in its own isolated context window. The main loop dispatches a scoped task, receives the result back, and keeps its own context clean, which is the whole point. The tradeoff appears in chains: if the lead's context fills up, handoffs lose detail, so keep chains to two or three steps and make each handoff verifiable.

How many subagents can Claude Code run at once before it gets expensive?

There is no hard cap, but cost scales with token burn, and polling status across many running agents burns tokens fast. Batch your check-ins instead of watching terminals continuously. Practically, past three or four parallel agents you become the glue again, tracking worktrees and pasting context, which is where orchestration tooling starts earning its keep.

Can I use subagents from a community repo in my own project without edits?

Rarely. Most published definitions are demos, not battle-tested configs. Before pasting anything into .claude/agents/, check three things: does it pin scope with bounded files and explicit acceptance criteria, does it state what the subagent must not touch, and does the author show it running on anything beyond a toy codebase. Treat every repo as a candidate, not a solution.

Do subagents work with other tools like Codex or Cursor Cloud Agents?

Subagent definitions are Claude Code specific, but the patterns transfer. Cursor Cloud Agents are separate sessions, closer to agent teams than subagents, and Aerunit dispatches Linear tickets to them with cross-repo awareness. The scoping logic, acceptance criteria, and worktree isolation described in this guide apply at any orchestration layer, whatever tool actually runs the agents.

What model should a subagent use versus the main session?

Match the model to the task inside the definition itself. Reserve Opus for architecture decisions and the main loop's judgment calls. Sonnet or Haiku handle mechanical sweeps like migrations, hygiene audits, and test runs fine. Revisit the choice whenever a subagent burns tokens without moving the diff forward; a wrong model tier is a common, quiet failure.