Blog
8 min read

Claude Code subagents: what isolation buys, measured

Claude Code subagents run in their own context. The agent file format, current defaults, and what a real review loop measured: 1,034k tokens held, 10.5k returned.

Igor LuchenkovIgor LuchenkovBuilding UI Verify
claude code subagentsclaude codecoding agentscode reviewagentic coding
Five review rounds drawn as long bars of 190,000 to 223,000 tokens each subagent held in context, next to slivers of 1,500 to 2,700 tokens each one handed back, totaling 1,034k in and 10.5k out.
On this page

The file below is a complete Claude Code subagent. Twenty-nine lines: a name, a description that tells the main agent when to use it, a list of tools it may touch, a model, and a prompt. Save it as .claude/agents/diff-reviewer.md and Claude Code can hand it a branch to review in a context of its own.

A reviewer subagent written for this post. The frontmatter pins Opus and leaves out Edit, Write, and Agent; the body is the review brief.

A Claude Code subagent is a separate agent that the main session starts for one task. In the words of the subagents documentation, it "runs in its own context window with a custom system prompt, specific tool access, and independent permissions" (checked 2026-11-02, Claude Code 2.1.316). It does not see the conversation that launched it, only the brief the main agent writes plus your CLAUDE.md and a git status snapshot. When it finishes, the main session gets its final report and nothing else. That last property is what this post measures, from my own review and design loops on UI Verify.

How do you create a subagent in Claude Code?

You write a Markdown file with YAML frontmatter in .claude/agents/ for the project or ~/.claude/agents/ for yourself. Two fields are required: name and description. The description is what the main agent reads to decide when to delegate, so write it as a trigger ("Use after a branch has changes, before opening a PR"). The optional fields that matter most are tools (an allowlist; leave out Edit and Write for a reviewer), model (opus, sonnet, haiku, fable, a full model id, or inherit), effort, skills to preload, mcpServers, and isolation: worktree for an agent that should edit in its own checkout.

Unknown frontmatter fields are ignored without an error, and a file with YAML that fails to parse is skipped, so a typo turns into a subagent that silently does something else. claude plugin validate .claude/agents checks the files. You can also skip files entirely: the main agent can launch the built-in general-purpose subagent with a written brief, and in my repository that is what happens almost every time.

What changed in subagent defaults this year

Most guides that rank for this topic were written against older versions, and four defaults have moved. Check the version you run against this list, dated 2026-11-02.

  • Background by default. A subagent spawned from the main conversation now starts in the background, and fork mode is on by default from 2.1.302; set CLAUDE_CODE_FORK_SUBAGENT=0 if you want the main agent to wait for it. In claude -p and the SDK it can still wait.
  • Nesting is allowed. A subagent can spawn subagents of its own, up to three layers below the main conversation.
  • Twenty at once. A spawn fails with a concurrency error at 20 running subagents, not 10.
  • Model precedence. The frontmatter model now beats CLAUDE_CODE_SUBAGENT_MODEL (changed in 2.1.251), and the Explore agent runs on the main session's model rather than Haiku. The tool that launches subagents was renamed from Task to Agent in 2.1.63.

What does a subagent cost and save?

To see the isolation directly, I ran the reviewer from the top of this post headless on a scratch branch with four planted pagination bugs: an off-by-one in the page offset, a Math.floor that drops the last partial page, a removed minimum, and two doc comments the change made false. The session ran Sonnet; the subagent's frontmatter pinned Opus. It found all four, plus a missing test, in 43 seconds for $0.20.

One headless run: all four planted bugs found, Opus subagent under a Sonnet session. The subagent peaked at 8.8k tokens of context; the main session at 37.0k.

The subagent's context peaked at 8,804 tokens while the main session's reached 37,001. A subagent starts with its own short system prompt instead of the full Claude Code one, so a narrow task in a fresh context is small. The bigger effect shows up on real work. In one review loop on a change of about 2,500 lines across 31 files, five Opus reviewer subagents held 1,034,105 tokens of context between them, each one reading the diff and the surrounding code for six to twelve minutes. They handed back 41,977 characters of reports, about 10,500 tokens. Roughly a hundred to one. None of the reading reached my main session, which stayed free to verify findings and make the fixes.

Two vendors as parallel seats

The review loop in my repo runs two reviewers on every round, launched in the same turn: a Claude subagent pinned to Opus, and Codex running as a background job pinned to a specific model and reasoning effort. Neither sees the other's output. The main session is the only place their findings meet, and it checks every finding against the code before anything gets fixed. Then the next round starts with fresh reviewers, so nobody reviews a fix while remembering why they suggested it.

One round of the review loop. Two independent seats, one verification step, then a fresh round. When Codex hits its usage limit, a second Opus subagent takes its seat.

Over that five-round loop the two seats raised 66 findings, and neither one dominated: Claude raised more in rounds 1 and 4, Codex in rounds 2, 3, and 5. In round 1 both models reached one finding independently, and three findings came from Claude alone, one of them a regression in the fix I had just made. In round 3 the verification step threw out a confident Codex finding that was simply wrong about how the two pull requests were stacked. And mid-review, the Claude seat noticed that main had taken the migration number our branch was using while the review was running.

Raw findings per round from each seat. Every one went through a check against the code before anything changed; the loop does not keep a finding just because two models agree.

Two rules make this work. First, verify instead of voting: a finding only one model raised stays if the code confirms it, and a finding both raised still gets checked. Second, be honest about the panel. When Codex is out of quota, two Claude subagents are not two models, and the loop says so in its summary. I wrote in my software factory post why a second vendor matters; the numbers above are what it looks like round by round.

How many rounds is enough?

Fewer than you would think for code, more than you would think for design. My review loop now stops when a round finds nothing that matters and caps at five rounds by default. It used to have no cap, and two fresh reviewers would keep finding wording issues and invented edge cases for eleven to fifteen rounds. A design loop is different, because a design can be wrong at the root. The night before that review, a design loop with two critic subagents and Opus as the architect ran fifteen rounds, past the default cap because I asked it to go until it converged.

Fifteen design rounds. The count only fell for good after the architect threw the approach away twice. Codex dropped out at round 8 and a second Opus critic took its seat.

The count dropped for good only after the architect stopped patching. After round 3 it wrote that each fix was making the design bigger and that the problem was the design itself; after round 6 it rewrote the model around a much simpler data shape. Round 15 came back with both critics returning the same two words, VERDICT: SOUND. The lesson for subagent loops: when critiques stop shrinking, the fix is a rewrite by one agent with the whole picture, not more critics.

When should you not use a subagent?

When the task needs the conversation. A subagent starts cold, so anything that depends on what we just discussed, or a quick edit where the brief would be longer than the change, belongs in the main session. Many subagents that each return long reports can also fill the main context they were meant to protect, so ask for findings in a fixed short format. Over seven weeks in this repository I launched 688 subagents across 80 sessions. Nearly all were general-purpose with a written brief, Explore was used seven times, and about 30% of launch turns started two or more at once. Code review, design critique, and research made up most of them.

Seven weeks of my sessions in this repository: 688 subagent launches, almost all a general-purpose agent with a written brief.

A subagent for visual review

Code reviewers, human or subagent, read the diff and not the rendered page, which is why a CSS change can pass every review and still break a screen. Visual triage is also the most context-hungry thing an agent does, because it looks at images. Both point the same way: give it its own subagent. UI Verify, our visual regression testing tool for coding agents, serves each changed screenshot over MCP as a before and after cropped to what moved. A triage subagent can look at every change in its own context and hand the main session one line per story.

.claude/agents/visual-triage.md
---
name: visual-triage
description: Reviews a UI Verify build's changed screenshots and sorts each into intended, regression or noise. Use after uiverify check or a CI visual check reports changes. Reports only; never accepts.
tools: Read, Grep, Glob, mcp__uiverify__get_build, mcp__uiverify__get_diff, mcp__uiverify__render_diff_image, mcp__uiverify__list_comments
mcpServers:
  - uiverify
model: opus
---

You triage one UI Verify build. The main session tells you the build and what the change was meant to do.

1. Call get_build for the changed stories.
2. For each one, call render_diff_image with which: "before_after" and look at the pixels.
3. Put every story in one bucket: intended, regression, or noise.
4. Report one line per story: story id, bucket, and the visible reason in a few words.

Do not accept, deny or comment. The main session decides.

This one is a recipe, validated but not yet part of my setup. The accept tools are left out on purpose, the same way the code reviewer gets no Edit or Write: the subagent reports, the main session decides. The triage-visual-changes skill carries the full procedure, and the tool reference lists what the server exposes. Hooks from your settings also fire inside subagents, so the guards in my hooks post apply to them too. Free to try with 10,000 snapshots a month, and 50,000 a month on open-source projects.

Give the reviewer subagent the pixels too

Code reviewers read the diff. UI Verify gives a triage subagent each visual change before and after over MCP, so the rendered UI gets reviewed in its own context as well.

Start for free

No credit card required.

ShareXLinkedIn
Related skill

Review loop

Review and fix until the diff is actually clean.