Updated 2026-07-10 for the agent-teams era. Originally published September 2025.
A subagent in Claude Code is a separate agent your session spawns to do a defined piece of work. It gets its own context window, its own tool permissions, optionally its own model, and it runs alongside anything else you have going. When it finishes, your main session gets a report, not a transcript.
Independent pieces of work run at the same time instead of one after another. And each piece burns its own fresh context instead of crowding into the one window where you are trying to hold the plan; a single session that reads everything bleeds detail across everything, while specialists with clean contexts don't.
I dispatch subagents every working day, mostly from a long-lived orchestrator session per project that hands out ticket work and collects results while I steer. What follows is how subagents work as of mid-2026, how to create and invoke them, the practices that survived daily use, and honest numbers on how far the parallelism goes.
%%{init: {"look": "handDrawn"}}%%
graph TD
O[Orchestrator session<br>holds the plan and context] --> S1[Subagent:<br>implement ticket A]
O --> S2[Subagent:<br>implement ticket B]
O --> S3[Subagent:<br>research the vendor API]
O --> S4[Subagent:<br>review the diff]
S1 --> R[Results converge]
S2 --> R
S3 --> R
S4 --> R
R --> O
One session fans out to parallel subagents; each works in its own context window and reports back a summary.
What Claude Code subagents are (and when to use them)
Mechanically, a dispatch goes through the Agent tool (older Claude Code versions called it the Task tool). You can let Claude spin up a general-purpose subagent on the fly, or define named specialists and hand work to them by name. As of mid-2026, subagents run in the background by default: you keep working in the main session, Claude Code notifies you when one finishes, and you can message a specific agent to continue it with its context intact instead of starting cold. A recurring cast of named agents behaves less like disposable processes and more like a small standing team.
Reach for a subagent when the work would flood your main context: codebase-wide searches, a vendor's documentation, a day of logs. Reach for several when a task splits into independent pieces, one agent per piece. And reach for one deliberately when a role must not share context with the work it judges; a reviewer that wrote the code is grading its own homework.
Skip the machinery when you already know the file and the question, since one direct read beats a dispatch. Skip it for work you want to steer turn by turn, and for edits so entangled that two agents would be rewriting each other's files.
Subagents also get confused with skills, and the distinction matters because the two compose. A skill is a markdown file of process knowledge loaded into an agent's context: how to ship a feature, how to structure a memo. A subagent is another set of hands with its own context. My build subagents load the same skills my main session uses.
%%{init: {"look": "handDrawn"}}%%
graph TD
W[New piece of work] --> K{Process knowledge the<br>agent should follow?}
K -- yes --> SK[Write a skill]
K -- no --> H{Independent enough to<br>hand off whole?}
H -- no --> M[Keep it in the<br>main session]
H -- yes --> L{Hours or days of work<br>on its own branch?}
L -- no --> SA[Dispatch a subagent]
L -- yes --> WT[Separate Claude Code instance<br>in a git worktree]
Skills teach process, subagents add hands, separate instances add whole workstreams.
Named subagents are markdown files: .claude/agents/ in a repo for project specialists, ~/.claude/agents/ for the ones you want everywhere. The /agents command inside a session creates and edits them interactively, but a file in git is the version you can review and roll back.
Here is a reviewer I would actually run:
---
name: code-reviewer
description: Reviews a diff for correctness, security, and untested claims. Use after any nontrivial implementation task.
tools: Read, Grep, Glob
model: inherit
---
You are a code reviewer. You did not write this code and you have
no stake in it passing.
Read the ticket, the diff, and the tests. Verify the change does what
the ticket claims, not what the commit message claims.
Report verdict first, then findings ordered by severity, each with
file and line. If you cannot verify a claim, say so explicitly.
Never pad the report with praise.
The frontmatter does real work. name is how you invoke it. description is how Claude decides to delegate automatically, so write it like a dispatch rule, not a bio. tools is a permission boundary: a reviewer with read-only tools cannot quietly "fix" the code it was asked to judge. model pins a cheaper model for mechanical roles, or a stronger one where the judgment lives.
The body is the agent's system prompt. Keep it short and opinionated, and treat the file like code: version it, review diffs to it, and when a subagent misses, patch the definition rather than correcting it in chat, so every future dispatch inherits the fix.
These files travel well, too. When I moved my workflow docs to a different coding agent they ported in minutes, because they are just markdown. The process you encode is the asset; the tool underneath is swappable.
How to invoke subagents (with examples)
Explicit dispatch is one sentence in your prompt:
Use the code-reviewer subagent on the diff for ticket 142.
Claude also delegates on its own when a task matches an agent's description field, which is why the description should read like a rule. Parallel dispatch is just asking for it; independent dispatches run concurrently:
Spawn three subagents in parallel: one to map every caller of
exportReport, one to read the payment vendor's webhook docs, one to
draft the migration plan. Each writes its findings to docs/notes/
and reports back a summary.
Four examples from my own use:
The divorced reviewer. After builders ship UI, a fresh read-only reviewer gets the evidence paths and a narrow charter. One of these gates caught a clipped mobile label. It also caught that the screenshots offered as proof never showed the section the work claimed to fix. An evidence gap and an implementation bug, cleanly separated, by an agent with no memory of building either.
The clean-room second concept. After two iterations on a design in one session, I spawn a fresh subagent with my distilled preferences and no sight of the existing draft, told to find its own thesis. Iterating in one context converges on the first idea's local maximum; a clean room with a preference brief diversifies, and I end up judging two real concepts head to head.
The cheap claim-checkers. Status documents inflate because "done" quietly means "exists." I hand a status page to a batch of small checker subagents on cheaper models and have them verify each concrete claim against the codebase. On one pass, most claims held at the code-exists level while the most forward-leaning delivery claims had thin or zero backing; every Done cell conflated registered with verified.
The planning trio. The first version of this post was built around this dispatch: a product-manager persona and a designer persona each write a memo from the real artifact before any builder starts. How that pre-build step once redirected an entire rebuild is its own post.
Claude Code subagent best practices
Ground the subagent in the real artifact first
A subagent given a role but nothing to read will invent its review, and it arrives fast. Every dispatch names its inputs: the diff, the file paths, the screenshots, the ticket. For judging roles, require the agent to read the artifact before it forms opinions; ungrounded opinions arrive fast and cost you a rerun.
Give every file one writer
Parallel subagents editing the same file is how hours of work disappear. Split by ownership before dispatching: this agent owns the API route, that one owns the component, nobody shares. If two pieces genuinely need the same file, they were never independent; run them in sequence.
Dispatch outcomes, not step lists
A subagent is a delegate, not a macro. If I were delegating to a senior engineer I would not dictate keystrokes, and the same rule holds here: state the outcome, the constraints, the anti-goals, and what proof to bring back. Then hold the line on the proof. A report that ends with test output, a screenshot path, or a written file is checkable; a summary alone is a vibe.
Let unattended agents decide and record
A background agent that stalls on a clarifying question wastes the point of being background. Mine make the reasonable call and log it to an assumptions file the reviewer reads later. Interactive runs may ask; autonomous runs record.
Health-check before you dispatch real work
At fan-out scale, dead sessions are normal, and they fail silently. Before handing out real work, ping each agent with "Reply with exactly: MODEL_OK." On an early fan-out run of mine, two of three pings came back empty, and each dead session cost about a minute to catch instead of surfacing hours later as mysterious zero progress.
Spend model quality where the judgment lives
At volume you get price conscious. Mechanical verification, claim-checking, and log-combing are exactly the work for cheap, fast models running in parallel. The orchestrator role, the one holding design decisions and integration context, is where I keep a strong model. The frontmatter model field is the knob.
How many Claude Code agents can you actually run in parallel?
More than the folklore says. The "2 to 5 agents is the realistic ceiling" advice that tops search results describes a person watching workers, and it stops applying the moment you manage orchestrators instead.
My normal shape as of mid-2026: 3 or 4 projects live at once, one long-lived orchestrator session per project, each orchestrator running around 5 subagents at a time. Call it 20 active tickets, and since subagents can spawn subagents where their tools allow it, count every live agent and it is often dozens.
On paper that is dozens of agents; in practice it feels like managing 4 people, because you talk to orchestrators, not workers. I ask an orchestrator "is this done? I have feedback on this," and it redispatches with the context intact.
The limits are real, they are just not where the folklore puts them. On my 32GB Mac mini, RAM gives out before my attention does. And everything that comes back needs review: one recent Sunday produced 66 commits across four repos from six sessions, and the only way to keep up was reviewing evidence bundles per PR instead of reading code line by line, which is its own topic. The rules I learned managing a swarm of 20 agents for a week still hold at this scale.
Subagents vs running multiple Claude Code instances in parallel
Searches for parallel Claude Code agents usually mean one of two setups, and they solve different problems. Subagents are in-session fan-out: one orchestrator, one working directory, a shared plan, parallel workers reporting back. Running multiple Claude Code instances in separate git worktrees is process-level fan-out: full isolation, one branch each, built for independent workstreams that live for hours or days. I run both daily, and the worktree workflow has enough of its own discipline, merge order, cleanup, and failure modes that it deserves its own post rather than a paragraph here.
Start with one file
Create .claude/agents/code-reviewer.md from the example above and run your next nontrivial diff through it. A judge with no stake in the code passing will tell you things your main session never will, and the dispatch habit builds from there.
Or skip the typing: point your coding agent at this post and ask it to set up the agent definitions and dispatch habits described here, adapted to your repo. The post is the spec. The whole pattern is one habit anyway: stop doing the work in the window where you keep the plan.
Discover more from zach wills
Subscribe to get the latest posts sent to your email.