Subagents

What Are Subagents?

Subagents are child instances of Claude that can be spawned to handle specific subtasks independently. When Claude Code encounters a complex task that would benefit from parallel execution, it can delegate portions of the work to specialized subagents.

Think of it like a lead developer breaking a large feature into smaller tickets and assigning each one to a different team member.

How Subagents Work

When Claude Code decides to use subagents, it follows this pattern:

1. Analyze — The primary agent analyzes the task and identifies independent subtasks
2. Spawn — Child agents are launched with focused, specific instructions
3. Execute — Each subagent works on its task with read access to the codebase
4. Report — Subagents return their results to the primary agent
5. Integrate — The primary agent combines results and applies the final changes

When Claude Uses Subagents

Claude Code may automatically use subagents for:

• Research tasks — Searching for patterns across a large codebase
• Multi-file analysis — Reading and analyzing many files simultaneously
• Complex refactoring — Handling different parts of a refactor in parallel
• Test writing — Generating tests for multiple modules at once

Example: Research Subagent

# You ask:
> How is authentication implemented in this project? Check all the relevant files.

# Claude may spawn subagents to:
# Subagent 1: Search for auth middleware files
# Subagent 2: Look for JWT/session handling
# Subagent 3: Check route protection patterns
# Subagent 4: Find user model and validation

# Each subagent searches independently, then results are combined
# into a comprehensive answer

Subagent Permissions

Subagents have more limited permissions than the primary agent:

• Can — Read files, search code, analyze patterns
• Cannot — Write files directly, run shell commands, or make destructive changes

Only the primary agent has write access. This ensures all actual changes go through the normal permission flow where you approve each change.

Triggering Subagents Effectively

While subagents are often used automatically, you can encourage their use with certain prompts:

# Wide-scope research prompts:
> Analyze all API routes and tell me which ones are missing error handling

# Multi-module tasks:
> Review the authentication, authorization, and user management modules
> for security vulnerabilities

# Comprehensive codebase tasks:
> Find all places where we directly access the database without
> using the repository pattern

Benefits of Subagents

• Faster results — Multiple searches happen concurrently
• Better coverage — Less likely to miss relevant files
• Focused analysis — Each subagent has a clear, narrow scope
• Safe — Read-only access means subagents can't accidentally break anything

What's Next

In the next episode, we'll explore Claude Code with GitHub — creating pull requests, reviewing code, handling issues, and integrating Claude into your Git workflow.