Claude Code Subagents: The Complete Guide (2026)

What subagents actually are, when they help, when they hurt, how to write good ones, and how they relate to running many Claude Code sessions in parallel.

What Is a Claude Code Subagent?

A Claude Code subagent is a specialized AI assistant you define as a markdown file with YAML frontmatter. The parent Claude session can delegate work to it via the Task tool, the subagent runs in its own fresh context window with its own system prompt and (optionally) a restricted toolset, and it returns a single text reply to the parent.

The point is not to add more intelligence. Subagents use the same underlying model as the parent. The point is context isolation: keep the parent session focused, hand off noisy or specialized work, get back a clean summary, and continue.

Parent session                    Subagent
─────────────                    ────────
"Find every place we use         ↓
 the legacy auth helper"     ──>  [fresh context]
                                  Grep, Read, Read, Read...
                                  (15 tool calls, 8KB of output)
                                  ↓
"Found 12 callsites in       <──  [returns one message]
 4 files: ..."
[parent context grew by 200      [subagent context discarded]
 tokens, not 8000]

That asymmetry — many internal steps in, one summarized message out — is the entire value proposition.

The Mental Model: A Disposable Coworker With No Memory

The most common mistake newcomers make is treating subagents like long-lived assistants with state. They are not. Each invocation:

• Starts with an empty context window
• Sees only its system prompt + the prompt the parent passes
• Cannot read prior conversation, other subagents' output, or what the parent did before
• Returns one final message and immediately terminates
• Has no persistent memory across invocations

Think of a subagent as a coworker you tap on the shoulder: "Hey, look up X and tell me what you find." They walk away, do the work, come back with the answer, and forget the entire interaction. The next time you tap them, it's a new person.

Anatomy of a Subagent File

Subagents live in one of two places:

• .claude/agents/<name>.md — project-level, checked into git, shared with the team
• ~/.claude/agents/<name>.md — user-level, personal, available across all projects

Project-level wins on name conflicts. Both are plain markdown with YAML frontmatter:

---
name: code-reviewer
description: Use proactively after writing or modifying code to catch bugs, security issues, and style problems before commit. Specializes in defensive review with concrete fix suggestions.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer with twenty years of experience.

Your job is to review the diff the parent agent just produced and report:

1. Bugs or logic errors (with file:line references)
2. Security issues (injection, auth bypasses, secret leaks)
3. Style and consistency problems
4. Missing tests for new branches
5. Anything that would block this from shipping

Be terse. Lead with severity. Skip praise. If the code is clean, say so in one sentence.
End with a verdict: SHIP / FIX FIRST / NEEDS DISCUSSION.

The frontmatter fields

The body below the frontmatter is the system prompt. It loads into the subagent's context every time it runs, so keep it tight — every token here is paid on every invocation.

How Delegation Actually Works

There are two ways a subagent gets invoked:

1. Auto-delegation (the parent decides)

When you ask the parent Claude to do something, it scans the available subagents' description fields and decides whether any match. If your description starts with "Use proactively when..." or "Use whenever..." Claude is more likely to reach for it without being told. This is why the description is the most important field in the file — it's literally the routing signal.

2. Explicit invocation (you decide)

You can tell the parent: "Use the code-reviewer subagent on this diff" or "Spawn three explorer subagents in parallel to map the codebase." The parent then issues Task tool calls naming the subagent.

# In your prompt to the parent
"Use the code-reviewer subagent to check the changes I just made"

# What the parent does internally
Task(subagent_type="code-reviewer", prompt="Review the diff in src/auth.py and report findings")

# What you see
[code-reviewer reports back: 2 bugs, 1 style issue, SHIP after fixes]

5 Production-Ready Subagent Examples

1. Code reviewer (defensive second pair of eyes)

---
name: code-reviewer
description: Use proactively after writing or modifying code. Reviews diffs for bugs, security issues, and missing tests with concrete file:line references.
tools: Read, Grep, Glob, Bash
---

You are a senior code reviewer. Read the diff or files the parent points you at.
Report only: bugs, security issues, missing tests, breaking changes.
Skip praise. Use file:line refs. End with SHIP / FIX FIRST / NEEDS DISCUSSION.

2. Codebase explorer (pattern hunting without polluting context)

---
name: explorer
description: Use when the user asks an open-ended question about the codebase that requires exploring multiple files. Returns a concise summary instead of dumping raw file contents into the parent context.
tools: Read, Grep, Glob
---

You are a codebase navigator. Explore the project to answer the parent's question.
Read files, grep for patterns, follow imports.
Return ONE summary message: what you found, where, and the implications.
Never paste large file contents. Use file:line references and 2-line excerpts only.

3. Test writer (specialized prompt the parent doesn't need loaded)

---
name: test-writer
description: Use when the user asks to add or expand tests for a specific module or function. Writes idiomatic tests matching the project's existing test style.
tools: Read, Write, Edit, Bash, Grep
---

You write tests that match the project's existing conventions.
Before writing anything: read 2-3 existing test files to learn the style.
Cover happy path, edge cases, and at least one failure mode.
Run the test suite when done. Return only: files added, what they cover, pass/fail status.

4. Migration planner (heavy reasoning, single answer)

---
name: migration-planner
description: Use when the user wants to plan a non-trivial migration (framework upgrade, database schema change, language port). Produces a step-by-step plan, not code.
tools: Read, Grep, Glob
model: opus
---

You are a migration architect. Do NOT write code. Produce a plan.
Read the relevant files. Identify risks, breaking changes, and ordering constraints.
Output: numbered step list, dependency graph, estimated risk per step, rollback strategy.

5. Security auditor (restricted tools = safety boundary)

---
name: security-auditor
description: Use when the user asks for a security review of code touching auth, secrets, user input, or external APIs. Read-only — cannot modify anything.
tools: Read, Grep, Glob
---

You are a security auditor. You have READ-ONLY access on purpose.
Look for: SQL injection, XSS, command injection, auth bypass, secret leakage,
unsafe deserialization, missing authz checks, IDOR, SSRF, open redirects.
Report severity (Critical / High / Medium / Low) with file:line and a fix sketch.

Running Subagents in Parallel

A parent Claude session can spawn multiple subagents in parallel by issuing several Task tool calls in the same response. They all execute concurrently, each in its own fresh context window, and the parent receives all the results when they finish.

# Parent issues three Task calls in one turn:
Task(subagent_type="explorer", prompt="Map the auth subsystem")
Task(subagent_type="explorer", prompt="Map the billing subsystem")
Task(subagent_type="explorer", prompt="Map the notifications subsystem")

# All three run concurrently. Parent receives three summaries.
# Total wall time: ~time of the slowest one, not the sum.

This is how you scan a large codebase in 30 seconds instead of 2 minutes — and the parent context only grows by the three summaries, not by every file each subagent read.

This is parallelism inside one Claude Code session. It is distinct from running multiple top-level Claude Code sessions concurrently (the next section).

Subagents vs Parallel Claude Code Sessions

The single most common confusion: "If I can run subagents in parallel, why would I ever need amux or multiple Claude Code sessions?"

Because they solve fundamentally different problems.

Rule of thumb: if the subtask is short, read-mostly, and feeds back into the parent's reasoning, use a subagent. If the subtask is a self-contained ticket that ends in a commit or PR, run it in its own Claude Code session. The two are complementary, not competitive.

Anti-Patterns That Waste Tokens

1. Subagents for one-line lookups

If you just need to read a single file, the parent can do it in one tool call. Spinning up a subagent costs you the system prompt overhead plus a delegation roundtrip. Bad trade.

2. Multiple subagents writing to the same files

Subagents share the parent's working directory. Two subagents editing src/auth.py simultaneously will clobber each other — there is no git worktree isolation. If two units of work touch overlapping files, run them as separate amux sessions in separate worktrees, not parallel subagents.

3. Vague descriptions

If your description is "helps with code", the parent will never auto-delegate. Make it imperative and specific: "Use proactively after writing Python tests to verify they actually run and assert something meaningful." Descriptions are the routing layer.

4. Bloated system prompts

Every token in the body of the subagent file is loaded on every single invocation. A 3KB system prompt called 20 times is 60KB of context overhead. Trim ruthlessly.

5. Subagents that try to be the parent

If your subagent ends up doing 30 tool calls, planning multi-step refactors, and asking for clarification — it should just be the main session, not a subagent. Subagents should be focused: one job, one return value.

6. Ignoring the “no memory” rule

Trying to have a subagent “remember” what happened in a previous invocation will silently fail. Pass any required context in the prompt, or use a real persistence layer (the board, notes, files on disk).

Writing Subagent Descriptions That Actually Get Picked

The description field is the entire interface between the parent and your subagent. Claude reads it, decides relevance, and either delegates or doesn't. Three rules:

Lead with the trigger condition

Start with when to use the subagent, not what it is.

# Bad
description: A code reviewer that finds bugs and style issues.

# Good
description: Use proactively after the user writes or modifies code. Reviews
the diff for bugs, security issues, and missing tests.

Use the words “use proactively” or “use whenever”

These phrases bias the parent toward auto-delegation. Without them, the parent often waits to be asked.

Be narrow, not broad

A subagent that does “general code things” will be picked at random. A subagent that does “security review of code touching auth, secrets, or user input” will be picked exactly when relevant.

Combining Subagents With amux for Real Throughput

The strongest setup uses both layers:

• amux at the outer layer: 10 Claude Code sessions running in parallel across 10 git worktrees, each owning a separate ticket from the kanban board.
• Subagents at the inner layer: each session uses a code-reviewer subagent before committing, an explorer subagent for codebase questions, and a test-writer subagent for coverage.

The outer layer multiplies wall-clock throughput — you ship 10 things in the time of one. The inner layer keeps each session's context clean and specialized so quality stays high. Subagents prevent each session from drowning in its own intermediate output; amux prevents you from drowning in sequential work.

# 1. Define a reusable code-reviewer subagent (checked into the repo)
echo '---
name: code-reviewer
description: Use proactively before committing. Reviews diffs for bugs and missing tests.
tools: Read, Grep, Bash
---
You are a senior code reviewer. Be terse. Lead with severity. End with SHIP / FIX FIRST.
' > .claude/agents/code-reviewer.md

# 2. Push 10 tickets to the amux board
amux board add "Add tests for auth/login.py"
amux board add "Migrate api/users.py to async"
amux board add "Fix bug #423 — duplicate notifications"
# ...etc

# 3. Spin up 10 amux sessions, each on its own worktree
for i in $(seq 1 10); do
  amux register worker-$i --dir ../myproject --worktree --yolo
  amux start worker-$i
done

# 4. Each worker claims a ticket, calls the code-reviewer subagent before
#    committing, and ships a clean PR — all in parallel.

See the Agentmaxxing guide for the full playbook on running parallel sessions, and Scaling to 50 Agents for what changes when you push past a single machine.

FAQ

How are subagents different from running multiple Claude Code sessions in parallel?

Subagents live inside one Claude Code session. They share the same terminal, the same working directory, and run under one parent's coordination. Multiple parallel Claude Code sessions (the amux model) are separate processes with their own git worktrees, their own dashboards, and the ability to run for hours without a parent. Subagents are best for context hygiene; parallel sessions are best for true throughput multiplication.

When should I use a subagent instead of just doing the work directly?

Use a subagent when (1) the task generates a lot of intermediate output you do not want polluting the main context, (2) it benefits from a specialized system prompt you do not want loaded in your main session, or (3) you want to run multiple lookups concurrently. Don't use a subagent for trivial reads — the delegation overhead exceeds the benefit.

Can subagents call other subagents?

In current versions, no — subagents do not have access to the Task tool. Treat the parent as the only orchestrator. If you find yourself wanting nested delegation, the work probably belongs in a separate top-level Claude Code session via amux instead.

Do subagents share memory with the parent?

No. Each invocation starts with a fresh context window seeded only by its system prompt and the prompt the parent passes in. Subagents cannot see prior tool results, other subagents' output, or conversation history.

What tools can subagents use?

Whatever you list under tools in the YAML frontmatter. Omit the field to inherit the parent's full toolset, or restrict it for safety (e.g., a research subagent gets only Read and Grep — it physically cannot modify files).

Where do I save subagent files?

Project-level at .claude/agents/ in your repo (checked into git, shared with the team) or user-level at ~/.claude/agents/ (personal, available across all projects). Project-level wins on name conflicts.

Should I use subagents or amux for parallel coding?

Both. Subagents inside a session for context efficiency and concurrent lookups. amux outside for true parallel throughput across isolated git worktrees with self-healing, monitoring, and per-session token tracking. They compose; they do not compete.

git clone https://github.com/mixpeek/amux && cd amux && ./install.sh
amux register myproject --dir ~/Dev/myproject --yolo
amux start myproject
amux serve  # → https://localhost:8822