Claude Code Subagents

Quick answer

Subagents are fresh Claude Code sessions dispatched from a parent session using the Agent tool. Each subagent starts with a clean context window, receives a focused task and the exact context it needs, then returns a result to the parent. Subagents are the fix for the classic problem of a session that has accumulated so much context that it becomes confused. The four main patterns are orchestrator plus workers, parallel independent agents, spec-then-implement, and review loops.

What a subagent actually is

A subagent is a child Claude Code session launched by the parent via the Agent tool. The parent specifies a task description and any files or context the child needs. The child runs to completion and returns a text result, which the parent sees as the output of a tool call.

Under the hood, the child runs with the same CLAUDE.md rules, the same settings.json, the same MCP servers. What differs is context: the child does not inherit the parent's conversation history. It starts clean.

Why fresh context matters

Long parent sessions pick up noise. Old file reads, earlier failed attempts, half-correct hypotheses, conversational detours. All of it sits in context and influences every next turn.

A subagent skips that baggage. When you need a hard task done well, a subagent with a tight prompt usually outperforms the same model doing the same task inside a cluttered parent session. The improvement is roughly 20-40% on tasks that depend heavily on precise reading.

This is the core argument for subagent-driven development: hard work goes to fresh agents, the parent orchestrates.

How to trigger a dispatch

Two ways:

1. Tell Claude in natural language: "Dispatch a fresh subagent to write the spec for this feature." Claude picks up the intent and uses the Agent tool.
2. Be more explicit: "Use the Agent tool with this exact prompt: ." Useful when you want the subagent prompt to be specific.

You can also configure skills that dispatch subagents as part of their workflow, so typing /spec kicks off a subagent without extra instructions.

What to include in a subagent prompt

The subagent starts with no context from the parent. Every piece of information it needs must be in its prompt:

• File paths the subagent should read first (absolute, not relative).
• Snippets of code if they are short enough to inline.
• The task, stated clearly with success criteria.
• Any constraints (do not touch files outside src/auth/, do not run network calls, return only the diff).
• The expected output format (markdown plan, JSON, a diff, a list of file paths).

What to leave out: conversational context from the parent, earlier failed attempts, anything unrelated to the current task. Brevity wins in subagent prompts.

Worktree isolation

To run a subagent on an isolated branch without polluting the parent working tree, use a git worktree:

git worktree add ../repo-sub-feat-login feat/login

Dispatch the subagent inside that worktree. Any edits, test runs, or commits happen on the branch without affecting the parent's working directory. When the subagent finishes, the parent can inspect the branch, merge it, or discard it.

The worktrees reference page covers setup and cleanup in detail.

Four subagent patterns

Pattern 1: Orchestrator plus workers

The parent session holds the plan and delegates each step to a worker subagent.

Flow:

1. Parent reads the spec and writes a numbered plan.
2. For each plan step, parent dispatches a subagent with the step's context and task.
3. Subagents return results; parent reviews and proceeds to the next step.
4. If a subagent's result is off, the parent can redispatch with tighter constraints.

Good for multi-step features where the plan is stable but execution is varied.

Pattern 2: Parallel independent agents

Multiple subagents run at the same time on tasks that do not share state.

Example: a large refactor that touches three unrelated areas (auth, billing, search). Dispatch three subagents in parallel, one per area. Each runs in its own worktree. The parent merges the branches once all three finish.

Parallelism cuts wall-clock time roughly proportionally to the number of agents, capped by how independent the tasks really are. Overlap in file edits causes merge conflicts, so the task split matters more than the agent count.

Pattern 3: Spec-then-implement

Two subagents in sequence:

1. Subagent A writes the detailed spec for a feature. Output is a markdown document.
2. Subagent B reads the spec and implements it, producing a diff or a commit.

The value of this pattern is that the spec pass tends to catch requirement gaps that implementation would otherwise paper over. Running the two stages in separate contexts keeps each focused.

Pattern 4: Review loop

Three subagents in sequence around an implementation:

1. Implementer subagent writes the code.
2. Spec reviewer subagent checks whether the code matches the spec.
3. Code-quality reviewer subagent checks naming, tests, edge cases, and performance.

The parent collects the two reviews and decides whether to merge, redispatch the implementer with feedback, or escalate to the user. This pattern is slower but produces higher quality output and catches issues that would otherwise ship.

Subagent-driven development

The pattern of pushing hard work into subagents and using the parent only as an orchestrator has a name: subagent-driven development. It differs from inline execution in two ways:

1. The parent never gets polluted by the file reads and tool calls of the hard task, so its own reasoning stays sharp across many tasks.
2. Each subagent focuses on one task with a clean context, so quality goes up per-task.

The tradeoff is cost: every subagent dispatch re-sends the CLAUDE.md and the prompt. For a 2,000-token CLAUDE.md and a 500-token prompt, that is 2,500 tokens per dispatch, or roughly 1 cent per subagent on Sonnet 4. A task that dispatches 20 subagents costs 20 cents in CLAUDE.md overhead alone.

For tasks where quality matters more than cost, the overhead is worth it. For quick one-off tweaks, inline execution is fine.

Context window preservation

A concrete example of the preservation benefit: parent needs to make three small changes across three unrelated files. Naive approach reads all three files into the parent's context plus runs the edits, adding 12,000 tokens of file content to the session forever. Subagent approach dispatches three subagents, one per change; each reads its one file and returns a one-sentence summary. The parent's context grows by 3 sentences, about 150 tokens, and 99% of the file content stays out.

Over a long session this adds up. A parent that stays at 30k tokens of context can sustain hard thinking across the whole session; a parent that has ballooned to 150k tokens loses nuance by the tenth task.

Practical example: 3-subagent feature flow

Suppose you are building a feature: add OAuth login with Google.

1. Parent dispatches subagent A: "Read docs/auth-spec.md and the existing src/auth/ directory. Write a detailed implementation plan as markdown, listing every file to create or modify and the signature of each new function." Return the plan.
2. Parent reviews the plan, iterates once, then dispatches subagent B: "Here is the approved plan: . Implement it. Touch only files listed in the plan. Run pnpm test after every file change. Return a commit-ready diff."
3. Parent dispatches subagent C: "Review this diff against the spec: . Check correctness, edge cases, test coverage, and naming. Return a list of blocking issues, suggested fixes, and optional polish."
4. Parent reads the review, optionally redispatches B with the blocking feedback, then commits.

Total cost on Sonnet 4: roughly $0.80 to $2.00 for a medium feature, compared to $0.40 to $1.00 for the same feature done inline. Quality is usually visibly higher.