Claude Code subagents: when to delegate, and how to brief them

A subagent is a separate Claude, with its own context window, that does one piece of work and hands back a summary. Use subagents to keep heavy reading out of your main session and to run independent work in parallel. They do not make work cheaper — a subagent’s tokens come out of the same usage limits as everything else — so delegate when the reading is large and the answer is small, and do it inline when the job is a handful of tool calls.

The ones you have, and the ones you write

Claude Code ships with a few: Explore, a fast read-only searcher; Plan, which gathers context during plan mode; and a general-purpose agent that can both explore and act. Your own are Markdown files with a short header:

---
name: code-reviewer
description: Use after a change is finished and before it is committed.
  Reviews the diff for bugs and missing tests. Read-only.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You review diffs. Report problems with file and line, most serious first.
Never edit files. If nothing is wrong, say so in one line.

Only name and description are required. As with skills, the description is what Claude reads when deciding whether to delegate, so phrase it as a condition. tools narrows what the agent may do (a reviewer that cannot edit is a reviewer you can trust), and model accepts sonnet, opus, haiku, fable, a full model ID or inherit.

What they cost

Each subagent sends its own requests, and those count toward the same plan limits as your main conversation. Several subagents reading in parallel spend several times the tokens, just faster. Two ways to spend less: give reading-heavy agents a smaller, cheaper model, and don’t delegate what the main session could do in a few steps — the briefing, start-up and summary have their own cost.

Delegate, or do it inline?

• Delegate a search across a large codebase or many documents, where you need the conclusion, not the file dumps.
• Delegate independent pieces of work that can run at the same time — research on several options, a review while you keep building.
• Delegate a second opinion: a fresh context reviewing a diff isn’t anchored on the reasoning that produced it.
• Inline when you already know the file, or the job is a few reads and an edit.
• Inline when the work needs the context of the current conversation; re-explaining it costs more than doing it.

Brief it like a colleague

A subagent starts knowing nothing about your conversation. Most poor subagent results we have seen trace back to a one-line brief. Ours now always carry:

1. The goal and the why — what the result is for, so the agent can make judgment calls.
2. What is already known — files, earlier findings, dead ends, so it doesn’t repeat them.
3. Scope — what to touch, what to leave alone, read-only or not.
4. The shape of the answer — a list, a yes/no with evidence, file paths.
5. A limit — a time or tool-call cap, and an instruction to return partial results when it hits it.

The last one is a lesson we paid for: a research agent without a limit stalled, kept going, burned a large share of a session’s budget and returned nothing usable. Now every long-running agent has a cap and must hand back what it has.

Running them in parallel

Background subagents run while you keep working, and Claude Code can run several at once — by default up to 20 per session, and subagents can start their own up to 3 layers deep. In practice we rarely run more than a few at a time: every result still has to be read and checked, and that review, not the agents, is the bottleneck.

What we checked

Read 2026-11-01 from Anthropic's subagents documentation and the common workflows guide.

Getting it set up

Subagents work best on top of a solid base — instructions, memory and a way to check the work; our free guide to setting up Claude Code properly covers it. AI Setup includes defining the first agents your work actually needs.