Claude Code Subagents: Parallel Processing for Complex Tasks

Key Takeaways#

• Subagents are independent AI assistants that run in their own context window — they don't consume your main conversation's context budget and return only a summary when done.
• Claude Code ships with built-in subagents (Explore, Plan, General-purpose) tuned for specific workloads; you can also define custom agents via markdown files or CLI flags.
• Model routing is the primary cost lever: send exploration to Haiku, reviews to Sonnet, and keep Opus for the complex main conversation only.
• The master-clone pattern (spawning copies of the general agent with key context in CLAUDE.md) often outperforms specialized custom subagents, which tend to gatekeep context and break under edge cases.
• Use isolation: worktree when a subagent needs to modify files without conflicting with the main agent's working directory.

What Are Subagents?#

Subagents are specialized AI assistants that handle specific tasks in their own context window. Unlike tool calls that execute inline within your main conversation, a subagent spins up a separate session with its own:

• Custom system prompt — defines the agent's role, constraints, and behavior
• Specific tool access — restrict which tools the agent can use (read-only, shell access, etc.)
• Independent permissions — separate approval flow from the main conversation
• Dedicated model — route to Haiku, Sonnet, or inherit the parent's model

When a subagent finishes, it returns only a summary back to the main conversation. The full intermediate steps, tool calls, and reasoning stay in the subagent's context — preserving your main window for higher-level work.

This architecture means you can parallelize work: while your main agent reasons about architecture, a subagent can explore the codebase, another can review a PR, and a third can run tests. Each operates independently and reports back.

Built-in Subagents#

Claude Code includes several subagents optimized for common workflows:

The Explore agent is the workhorse — Haiku-powered and read-only, it's essentially free. Use it liberally for directory mapping, reference finding, or call-chain tracing.

Creating Custom Subagents#

Interactive Mode#

Run /agents in the Claude Code REPL, navigate to Library, then Create new agent. Fill in the name, description, prompt, and configuration. The agent saves to your project's .claude/agents/ directory.

File-Based: Markdown with YAML Frontmatter#

Create a .md file in .claude/agents/ with YAML frontmatter:

---
name: reviewer
description: Reviews code for bugs, style issues, and security vulnerabilities
model: sonnet
tools:
  - read_file
  - search_files
  - glob
disallowedTools:
  - terminal
  - write_file
  - patch
permissionMode: ask
maxTurns: 25
---

You are a senior code reviewer. Read the files provided and report:
1. Bug risks
2. Style violations
3. Security vulnerabilities
4. Suggested improvements

Be concise. Use [bullet points](/tools/bullet-points). Prioritize by severity.

Place this at .claude/agents/reviewer.md and it's available immediately.

CLI-Defined: JSON via --agents Flag#

Pass agent definitions directly on the command line:

claude --agents '{
  "reviewer": {
    "description": "Code review specialist",
    "model": "sonnet",
    "tools": ["read_file", "search_files"],
    "permissionMode": "ask",
    "prompt": "You are a senior code reviewer..."
  },
  "explorer": {
    "description": "Deep codebase explorer",
    "model": "haiku",
    "tools": ["read_file", "search_files", "glob"],
    "prompt": "Thoroughly explore and summarize code structure..."
  }
}'

This is useful for one-off agent configurations or CI pipelines where you don't want persistent agent files.

Subagent Frontmatter Fields#

The Master-Clone Architecture#

Research from blog.sshh.io reveals a critical insight: specialized custom subagents are often the wrong abstraction. When you define narrow specialist agents, you gatekeep context — the specialist can't see what others know, and edge cases fall through the gaps.

The better pattern is master-clone: use Claude's built-in Task(...) to spawn clones of the general-purpose agent. Each clone gets the same CLAUDE.md context. The main agent decides when and how to delegate based on the actual task, not a rigid role hierarchy.

<!-- CLAUDE.md -->
# Project Context

This is a TypeScript monorepo with three packages: core, cli, web.
Tests use Vitest. Linting uses ESLint with flat config.
API routes follow /src/routes/*.ts pattern.

When you need parallel work, spawn Task agents with this context.
Let the main conversation handle orchestration.

The main agent reads this, understands the full project context, and delegates intelligently — not because it was told "you are the test writer" but because it sees that tests need writing and knows how this project's test infrastructure works.

Custom subagents still have their place — particularly for restricting capabilities (read-only review, sandboxed exploration). But for complex multi-step work, give the general agent the context instead.

Worktree Isolation#

When a subagent modifies files, it can conflict with the main agent's working directory. Set isolation: worktree to create an isolated copy:

---
name: experiment
description: Run experimental code changes without affecting main directory
isolation: worktree
tools:
  - read_file
  - write_file
  - patch
  - terminal
---

The subagent gets its own git worktree — a separate checkout of the same branch. Changes don't appear in your main working directory until you review and merge. Essential for:

• Running speculative refactors that you might discard
• Parallel agents that modify the same files
• Test runs that generate artifacts you don't want in your main tree

Cost Optimization#

Model routing is the biggest cost lever with subagents:

# Cheap exploration agent
model: haiku
tools: [read_file, search_files, glob]

# Mid-tier review agent
model: sonnet
tools: [read_file, search_files]

# Don't create an Opus subagent — put Opus context in the main conversation

The math: if Opus costs $15/MTok and Haiku costs $0.25/MTok, every exploration task routed to Haiku saves ~60x. A typical session spawns 5-10 Explore calls — real savings with zero quality loss.

Memory Scope#

Subagent memory determines what context persists between invocations:

• User (memory: user) — Persists across all projects. Useful for personal preferences, coding style, or tool configurations that follow you everywhere.
• Project (memory: project) — Scoped to the current project. Store project-specific conventions, architecture decisions, or team norms. This is the default and most common choice.
• None (memory: none) — No memory. The subagent starts fresh every time. Use for one-shot tasks where prior context would add noise.

Most custom subagents should use memory: project so they accumulate relevant context over time without leaking between projects.

When to Use Subagents vs Agent Teams#

Subagents operate within a single Claude Code session. The main agent spawns them via Task(...), they run, return a summary, and the main agent continues. Use subagents when you need parallel work within one session and the task has clear boundaries.

Agent Teams coordinate across separate Claude Code sessions. Each agent is an independent process with its own REPL, conversation history, and terminal, communicating through shared files or MCP tools. Use agent teams when each agent needs a long-lived independent conversation or operates on different projects.

Rule of thumb: if it fits in one session, use subagents. If you need independent lifecycles, use agent teams.

Quick Reference#

# Spawn an Explore agent (Haiku, read-only, cheapest)
# Use for: file search, codebase mapping, reference finding

# Define a custom agent via file
.claude/agents/reviewer.md

# Define agents via CLI
claude --agents '{"reviewer": {...}}'

# Isolate filesystem with worktree
isolation: worktree

# Route by cost
# Haiku: exploration, search
# Sonnet: review, docs, moderate reasoning
# Opus: main conversation only, complex decisions

Subagents are not a replacement for good context management. They're a tool for preserving the context you have — offloading work that doesn't need the full weight of your main conversation into lighter, cheaper, parallel sessions. Use them to keep your main agent focused on what matters.