Skip to main content

Subagents & Parallel Agents

Advanced
What you'll learn
  • What a subagent is — a separate Claude with its own context window and a scoped toolset
  • The three reasons to delegate: protect context, specialize, and parallelize
  • The built-in agents Claude already delegates to: Explore, Plan, General-purpose
  • How to define your own subagent in .claude/agents/ and why description + tools are the two load-bearing fields
  • When NOT to parallelize, and how this connects to API agents and fleet-scale workflows

A subagent is a separate Claude instance with its own context window and a scoped set of tools, that your main session delegates a chunk of work to. It reports back a result, not its whole transcript — so the main session stays focused and uncluttered.

Why delegate​

Three jobs, one tool. Keep these in mind every time you reach for a subagent:

  • Protect the main context. A research dive or a big file sweep can burn thousands of tokens; do it in a subagent and only the conclusion returns.
  • Specialize. Give a subagent a tailored system prompt and only the tools it needs (e.g. a read-only reviewer).
  • Parallelize. Run independent subtasks at once — e.g. explore three modules simultaneously.

The built-ins you already have​

Before you define your own, know that Claude Code ships with subagents it delegates to automatically:

Built-inWhat it does
ExploreA fast, read-only agent for searching and understanding a codebase without touching it. As of Claude Code v2.1.198, Explore inherits the main conversation's model (capped at Opus on the Claude API) instead of always running on Haiku — override with a user/project subagent named Explore and model: haiku to keep it cheap.
PlanGathers context during plan mode so research stays out of the main, read-only conversation.
General-purposeA full-tool agent for complex, multi-step work that mixes exploration and changes.

You rarely invoke these by name; Claude reaches for them when a task fits. Custom subagents are for the workers you keep re-creating with the same instructions.

Defining your own​

A subagent is a Markdown file with YAML frontmatter (the body becomes its system prompt). Only name and description are required; everything else is optional. Store it per-project in .claude/agents/ (check it into git so the team shares it) or per-user in ~/.claude/agents/. Ask Claude to write one for you, or create the file by hand — as of Claude Code v2.1.198, running /agents no longer opens an interactive wizard; it just reminds you to edit .claude/agents/ directly.

Guided walkthrough1 of 5
  1. Per-project in .claude/agents/ (commit it so the team shares it) or per-user in ~/.claude/agents/.

A starter code-reviewer subagent:

code-reviewer subagent (.claude/agents/code-reviewer.md)

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior reviewer. Read the changed files, then report only
high-confidence issues: correctness bugs, security risks, and missing
tests. For each, show the file:line, the problem, and a concrete fix.
Do not restate what the code does. Never edit files.

Two things make a subagent good:

  • The description is the routing signal. Claude reads it to decide when to delegate, so write it like a trigger — "Use proactively after code changes" pulls it in automatically; a vague "helps with code" won't. This is the single highest-leverage line in the file.
  • Scope tools tightly. The tools field is an allowlist (or use disallowedTools as a denylist). A reviewer that can only Read, Glob, Grep cannot accidentally edit your code — the restriction is a guarantee, not a hint. Omit tools and the subagent inherits everything the main session has.

Worked example: a parallel review fan-out​

You finished a feature touching three modules and want a fast, independent check of each. In your main session:

Fan out three reviewers at once

Review the changes in auth/, billing/, and api/ — use the code-reviewer subagent on each, in parallel.

Claude spawns three code-reviewer instances at once. Each reads only its module, burns its own context on the file contents, and returns a short findings list. Your main session never sees the raw diffs — only three tidy reports — and the whole thing finishes in roughly the time of the slowest single review instead of the sum of all three. Because the reviewer is read-only, three agents working at once can't collide on a write.

When NOT to parallelize​

Watch out
  • Dependent steps must be sequential — don't fan out work where step B needs step A's output.
  • Shared file writes can conflict; isolate them (see Git Worktrees) or serialize.
  • Coordination overhead can exceed the benefit for small tasks. Delegate when the subtask is sizeable and independent.

For isolating conflicting writes, see Git Worktrees.

Subagent vs the API/SDK "agents"​

This page is about Claude Code's built-in delegation. Building your own agents programmatically is Building Agents on the API. The mental model — a goal, a tool loop, isolated context — is the same.

Common mistakes​

Pitfalls — flip each card for the fix
Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 4

When a few agents isn't enough​

Delegating a handful of subagents per turn is this page's bread and butter. When a task needs dozens or hundreds of agents — a codebase-wide sweep, a 500-file migration, research cross-checked across many sources — the orchestration outgrows a single context window. That's what Dynamic Workflows & ultracode are for: Claude writes a script that holds the plan, and a runtime fans the agents out in the background.

Check yourself

0/3
  1. Which field in a subagent's frontmatter is the routing signal Claude reads to decide WHEN to delegate?
  2. A reviewer subagent is given tools: Read, Glob, Grep. What does that allowlist guarantee?
  3. When does parallelizing subagents NOT help?
Key takeaways
  • A subagent is a separate Claude with its own context window and scoped tools; it returns a result, not its transcript.
  • Delegate to protect the main context, to specialize, or to parallelize independent work.
  • Claude already ships Explore, Plan, and General-purpose built-ins and reaches for them automatically.
  • name and description are the only required frontmatter fields — and description is the routing signal that decides when Claude delegates.
  • A tools allowlist turns intent into a guarantee; only fan out independent subtasks, and isolate shared writes.

Next​