Subagent Types
Claude Code has built-in subagent types, each optimized for different tasks:
1. Explore Agent
Purpose: Research, investigation, discovery
Optimized for:
- Searching code and files
Tools available:
When to use:
2. Plan Agent
Purpose: Architecture, design, planning
Optimized for:
Tools available:
When to use:
3. General-Purpose Agent
Purpose: Anything not covered above
Tools available:
When to use:
---
Creating Custom Subagent Definitions
You can define specialized subagents in .claude/agents/ directory. Each is a .md file with frontmatter.
File Format
Create .claude/agents/my-agent.md:
---
type: agent
description: What this agent specializes in
model: sonnet (or opus, haiku)
tools:
- Read
- Bash
- Grep
---
System instructions here. Tell the agent:
Its role
What it should focus on
How to approach problems
Output format expected
Complete Example
---
type: agent
description: Code reviewer specializing in security vulnerabilities
model: sonnet
tools:
- Read
- Grep
- WebSearch
---
You are a security code reviewer with deep expertise in:
OWASP top 10 vulnerabilities
TypeScript/JavaScript security best practices
Database security (SQL injection, etc)
Authentication and authorization patterns
When reviewing code:
Check for injection vulnerabilities
Identify authentication/authorization issues
Look for exposed secrets or credentials
Check for proper error handling
Verify crypto is used correctly
Format your response as:
Issue: [name]
Severity: Critical/High/Medium/Low
Location: [file:line]
Fix: [suggested change]
How Claude Code Finds Your Agent
.claude/agents/{name}.md---
Foreground vs Background Execution
Foreground (Default)
Main session waits for the subagent to complete before continuing.
You: "Use the researcher agent to find all API endpoints"
Timeline:
[0s] Main starts researcher subagent
[0s] Main waits... pauses...
[45s] Researcher completes with findings
[45s] Main receives results, continues
When to use:
Background
Main session continues without waiting. Subagent runs independently.
---
type: agent
description: Run integration tests
background: true
---
You: "Spawn a test runner in the background to validate changes"
Timeline:
[0s] Main starts test runner (background)
[0s] Main continues (doesn't wait)
[2s] You ask more questions, main keeps working
[35s] Test runner finishes in the background
[35s] You see "Test runner completed: 45 passed, 0 failed"
When to use:
---
How to Invoke Subagents
Automatic Invocation
Claude Code automatically decides to spawn a subagent based on your prompt:
You: "Research all the JWT implementations in this codebase"
Claude thinks: "This is a research task ā spawn Explore subagent"
Result: Explore agent runs, returns findings
Explicit Request
Tell Claude Code exactly which agent to use:
You: "Use my code-reviewer agent to audit auth.ts for security issues"
Claude: "You explicitly requested code-reviewer ā spawning it now"
Result: code-reviewer agent runs and returns security analysis
Mention in Messages
Send messages to running subagents:
You: "@researcher, also check for deprecated API calls"
Researcher: Gets your message, searches for deprecated calls, reports back
---
Context Isolation & Efficiency
Why Subagents Save Context
Imagine an Explore subagent reads 20 files while researching.
Without subagents:
With subagents:
Real Numbers
Task: "Research how authentication works and create an implementation plan"
Option 1: No subagents
- Read 15 auth files (context bloat)
- Summarize each one (more context)
- Design plan
- Total context used: ~50,000 tokens
Option 2: Explore subagent + Plan subagent
- Explore reads 15 files, returns 200-word summary
- Plan reads summary + your codebase, creates plan
- Total context used: ~25,000 tokens (50% savings!)
---
Key Gotchas
Gotcha #1: Subagents don't inherit history
Gotcha #2: Limited tool visibility
Gotcha #3: Subagents can't spawn subagents
Gotcha #4: Results are summarized
---
Best Practices
Design Agents for Specific Domains
---
type: agent
description: JavaScript/TypeScript test writing specialist
---
Not generic. Be specific. "Test writing specialist" is better than "helper."
Provide Clear Context in Prompts
ā Wrong: "Use the researcher to find the issue"
ā Right: "Use the researcher to find where we handle 404 errors in api/handlers.ts"
Use Foreground for Quick Tasks
Foreground = 30 seconds to a few minutes
Background = Long tasks (5+ minutes)
Combine Agents Strategically
Good combo:
- Explore agent researches patterns
- Plan agent designs solution
- Implementation agent codes it
Avoid:
- 5+ agents for a simple task (overhead)
- Overlapping responsibilities (confusing)
---
Summary
| Concept | What It Is | |
|---|---|---|
| ----------- | ||
| Subagent | Specialized Claude Code instance for specific task | |
| Types | Explore (research), Plan (design), General-purpose | |
| Foreground | Main waits for subagent; use for immediate results | |
| Background | Main continues; use for long-running tasks | |
| Context isolation | Subagent reads files, main only sees summary |
Next module: Meet the Agent SDK ā using agents in your own code!