Subagents
Subagents let you delegate specific subtasks to specialized agents. They're isolated—separate conversations with independent context. This keeps main threads focused while letting parallel agents handle detailed work.
Use cases
- Parallel subtasks: Break complex work into isolated chunks that run independently.
- Role specialization: Spin up expert agents (e.g., a testing specialist, a documentation writer).
- Context isolation: Keep main threads clean—subagents handle noise (research, parsing logs).
- Sandboxed experiments: Try risky changes without affecting the main agent's state.
What are subagents?
Subagents are fully functional Claude Code instances running independently from the main agent. Think of them as coworkers you spin up for specific jobs. Each subagent has:
- Independent conversation context: It doesn't share your main thread's memory.
- Full tool access: File operations, git commands, bash execution—same capabilities as the main agent.
- Isolated workspace: Changes happen in the same filesystem, but decisions are independent.
- Automatic cleanup: When done, the subagent's context disappears—work persists, clutter doesn't.
Key behaviors
When subagents make sense
- Clear subtask boundary: "Write unit tests for auth module" or "Research rate limiting patterns."
- Independent decisions: The subtask doesn't need back-and-forth with the main agent.
- Parallel execution: Multiple subagents can run at once (each in its own thread).
When to avoid subagents
- Tight coupling: If the subtask requires constant main-agent input, keep it in the main thread.
- Trivial tasks: Reading a file or running
ls? Don't delegate—use tools directly. - State synchronization: If success depends on coordinating with the main agent mid-task, subagents add friction.
How to use subagents
Basic syntax
Request a subagent by asking Claude Code to delegate a task:
Create a subagent to write integration tests for the API endpoints.
Claude Code will:
- Spin up the subagent in a new thread.
- Give it clear instructions (you can review and refine).
- Let it work autonomously.
- Report results back to you.
Example workflow
Main agent context:
You: Refactor the authentication module. Use a subagent to handle test updates.
Claude Code response:
I'll refactor the auth module. Spinning up a subagent to update tests in parallel.
Subagent task: Update all authentication tests to match the new AuthService interface.
Subagent (in separate thread):
[Subagent analyzes AuthService changes]
[Subagent updates test files]
[Subagent runs test suite]
Result: 24 tests updated, all passing.
Main agent:
Refactoring complete. Subagent reports tests are updated and green.
Controlling subagents
You can guide subagent behavior through your instructions:
Create a subagent to research best practices for rate limiting.
Give it access to WebSearch and limit the task to 15 minutes.
Claude Code will configure the subagent accordingly (tools, constraints, focus).
Best practices
1. Define clear deliverables
Bad:
Subagent: Make the code better.
Good:
Subagent: Refactor UserRepository to use the Builder pattern and update all call sites.
2. Isolate noisy work
Use subagents for tasks that generate clutter (logs, research notes, experimental code):
Main agent: Implement feature X.
Subagent: Parse the 5,000-line API spec and extract endpoint schemas.
3. Parallelize when possible
Multiple independent subtasks? Spin up multiple subagents:
Subagent A: Write unit tests for controllers.
Subagent B: Write integration tests for database layer.
Subagent C: Update API documentation.
4. Review before merging
Subagents work autonomously, but you're the integrator. Always review their output:
Subagent completed tests. Review: [show me the diff]
5. Don't over-delegate
If the task needs your judgment every 2 minutes, keep it in the main thread.
Technical details
Context boundaries
- Filesystem: Shared (changes persist).
- Conversation history: Isolated (subagent doesn't see main thread messages).
- Tool state: Independent (separate bash sessions, git state, etc.).
Lifecycle
- Spawn: Main agent creates subagent with task definition.
- Execute: Subagent runs autonomously (can use all tools).
- Report: Subagent summarizes results to main agent.
- Cleanup: Subagent context is discarded (work persists).
Communication
- One-way: Main agent → subagent (via task definition).
- Results-only: Subagent → main agent (summary at completion).
- No mid-task sync: Subagents don't interrupt the main agent for input.
Limitations
- No shared memory: Subagents can't access the main thread's conversation context.
- No real-time coordination: If the main agent changes strategy, the subagent won't know unless you cancel it.
- Resource overhead: Each subagent is a full Claude Code instance—don't spawn dozens simultaneously.
Example patterns
Research assistant
Main: Implement OAuth2 flow.
Subagent: Research OAuth2 security best practices and create a checklist.
Test specialist
Main: Refactor PaymentService.
Subagent: Generate comprehensive unit tests for the new PaymentService API.
Documentation writer
Main: Build new API endpoints.
Subagent: Write OpenAPI specs and usage examples for the new endpoints.
Experiment sandbox
Main: Consider migrating to library X.
Subagent: Prototype library X integration in a feature branch and report findings.
FAQ
Q: Can subagents create their own subagents? A: No. Only the main agent can spawn subagents (prevents runaway delegation).
Q: How do I cancel a subagent?
A: Ask the main agent: Cancel the test generation subagent.
Q: Can I talk to a subagent directly? A: No. Subagents are autonomous. Communicate through the main agent.
Q: Do subagents cost extra? A: They use API calls like any Claude Code operation. Be mindful of parallel subagents.
Q: Can subagents access secrets/env vars? A: Yes—same permissions as the main agent. Don't delegate sensitive tasks to untrusted code.
Next steps:
- Try delegating a test-writing task to a subagent.
- Use subagents for research tasks that would clutter your main thread.
- Experiment with parallel subagents for independent refactoring work.