Sub-Agents: Parallel Thinking

When you're working on a complex task, you often need to do several things at once: research an API while scaffolding a component, or review multiple files while planning a refactor. Your brain can't truly parallelize, but Claude Code can.

Sub-agents are separate Claude instances that run alongside your main session. Each has its own context, its own instructions, and can work independently. Think of them as specialists you can spin up on demand.

Why Sub-Agents?

A single Claude session has one context window. That's fine for focused tasks, but falls apart when you need to:

• Research a library's API while writing code that uses it
• Explore a codebase you've never seen before without polluting your working context
• Run multiple analysis passes in parallel (security, performance, accessibility)
• Isolate risky exploration from your main working session

Sub-agents solve all of these. Each agent gets its own context, does its work, and reports back.

Creating an Agent

Agents live as Markdown files in your project:

.claude/agents/<name>/AGENT.md

Each agent file has YAML frontmatter that defines its behavior, followed by Markdown instructions.

Agent File Structure

---
name: Explorer
description: Read-only codebase exploration and analysis
agent-type: Explore
tools:
  - Read
  - Glob
  - Grep
  - Bash(git log:*)
  - Bash(wc:*)
model: sonnet
---
 
# Explorer Agent
 
You are a read-only exploration agent. Your job is to understand
codebases and report findings. Never modify files.
 
## What to do
 
1. Map the directory structure
2. Identify key patterns and conventions
3. Report back with a clear summary
 
## What NOT to do
 
- Never create or edit files
- Never run destructive commands
- Never install packages

Frontmatter Options

Agent Types

There are three types of sub-agents:

General-purpose -- The default. Can read, write, and execute. Use for tasks that need to produce output.

Explore -- Read-only. Can read files, search, and analyze, but cannot modify anything. Perfect for research and investigation where you want safety guarantees.

Plan -- Proposes changes without executing them. Produces a plan that you review before acting on it.

Context Modes

The context field controls how the agent receives context from the parent session:

fork (default) -- The agent gets an isolated copy of the conversation state. Changes in the agent don't affect the parent. Best for independent tasks.

inline -- The agent runs within the parent's context. It sees what the parent sees and its actions are visible to the parent. Best for tightly coupled tasks.

How Agents Get Invoked

There are two ways Claude activates sub-agents:

Explicit: @mention

Type @agent-name in your prompt, and Claude will route the task to that agent:

@explorer Map the authentication flow in this codebase

@reviewer Check this PR for security issues

Automatic: Claude decides

Claude reads each agent's description field and can decide to invoke an agent when the task matches. If you have a security-reviewer agent with description "Reviews code for security vulnerabilities", Claude may invoke it automatically when you ask for a security review.

Practical Examples

Research Agent

When you need to understand an unfamiliar API or library before using it:

---
name: Researcher
description: Deep research on APIs, libraries, and technical concepts
agent-type: Explore
tools:
  - Read
  - Glob
  - Grep
  - WebSearch
  - WebFetch
model: sonnet
---
 
# Researcher
 
Research technical topics thoroughly. Return structured findings with:
- Key concepts and terminology
- Code examples from official docs
- Common pitfalls and gotchas
- Recommended patterns

Code Review Agent

A dedicated reviewer that checks for specific patterns:

---
name: Code Reviewer
description: Reviews code changes for bugs, security issues, and best practices
agent-type: Explore
tools:
  - Read
  - Glob
  - Grep
  - Bash(git diff:*)
  - Bash(git log:*)
model: sonnet
---
 
# Code Reviewer
 
Review code with focus on:
1. Logic errors and edge cases
2. Security vulnerabilities (injection, auth bypass, data exposure)
3. Performance issues (N+1 queries, unnecessary re-renders)
4. Consistency with existing patterns in the codebase
 
Rate each finding as P1 (must fix), P2 (should fix), or P3 (nice to have).

Documentation Agent

Generates docs by analyzing your actual code:

---
name: Documenter
description: Generates documentation from code analysis
agent-type: Explore
tools:
  - Read
  - Glob
  - Grep
model: sonnet
---
 
# Documenter
 
Generate clear, concise documentation by reading the actual source code.
Never invent APIs or features -- only document what exists.
Include code examples pulled from the codebase.

Exercise

mkdir -p .claude/agents/architect

---
name: Architect
description: Read-only architecture analysis and codebase mapping
agent-type: Explore
tools:
  - Read
  - Glob
  - Grep
  - Bash(git log:*)
  - Bash(wc:*)
  - Bash(ls:*)
model: sonnet
---
 
# Architect Agent
 
Analyze this codebase and produce a structured architecture report:
 
1. **Directory structure** - What lives where and why
2. **Entry points** - Where does execution begin
3. **Data flow** - How data moves through the system
4. **Key abstractions** - Patterns, base classes, shared utilities
5. **Dependencies** - External packages and what they're used for
6. **Conventions** - Naming, file organization, coding patterns

@architect Map the architecture of this project

When to Use Sub-Agents vs. Doing It Yourself

Not every task needs an agent. Use them when:

• The task is independent and doesn't need back-and-forth with you
• You want read-only safety (Explore type) for investigation
• You need parallel execution across multiple concerns
• The task would clutter your main context with intermediate work

For simple, sequential tasks, just ask Claude directly. Agents add overhead -- use them when the parallelism or isolation pays off.