Subagents
Subagents let a single agent spawn additional agents to work in parallel. Use subagents to tackle complex multi-part tasks faster by distributing work across isolated agent instances.
How subagents work
When an Agent is given a large task, it can choose to decompose it into subtasks and delegate each to a subagent. Each subagent:
- Runs in its own isolated conversation context.
- Has access to the same tools as the parent agent.
- Reports results back to the parent agent when complete.
- Can spawn its own subagents (up to 3 levels deep).
The parent agent coordinates the results and synthesizes a final response.
Subagents are most powerful for tasks that are naturally parallelizable — like writing tests for multiple modules, translating a codebase to TypeScript, or researching multiple approaches to a problem simultaneously.
Creating subagents
Subagent behavior is configured in your .agents/ directory:
.agents/
subagents/
code-reviewer.md
test-writer.md
documentation-writer.mdEach file defines a specialized subagent persona:
---
name: test-writer
description: >
A specialized agent that writes comprehensive unit tests.
Activate when: "write tests", "add tests", "test coverage"
---
# Test Writer Subagent
You specialize in writing unit tests. When activated:
1. Read the target file to understand the API surface
2. Identify all edge cases and error paths
3. Write tests that cover happy path + edge cases + error cases
4. Use the test patterns in `examples/` as your reference
5. Report back a summary of coverage addedCommunication between subagents
Task delegation
Parent agent sends a clear task description + relevant files to each subagent. Subagents don't share state directly.
Result synthesis
When all subagents finish, the parent reads their outputs and synthesizes a cohesive result before responding to you.
Use cases
Parallel test writing
"Write unit tests for every service in
src/services/. Each service gets its own test file."
The agent identifies all service files, spawns one subagent per service, and each writes tests in parallel. A task that might take 10 sequential tool calls finishes in 2-3 minutes instead of 10+.
Multi-language migration
"Migrate all JavaScript files in
src/utils/to TypeScript."
Agent spawns one subagent per utility file. Each subagent handles the migration independently, then the parent reviews and consolidates.
Research and compare approaches
"Research three different approaches for implementing real-time features: WebSockets, SSE, and long-polling. Compare them for our use case."
Agent spawns three subagents, each researching one approach. The parent synthesizes a comparison.
Documentation generation
"Write documentation for every exported function in our public API."
Agent spawns subagents per module, each writing JSDoc and markdown documentation. Much faster than sequential generation.
Each subagent uses model tokens independently. A large subagent workflow can consume significantly more tokens than a single sequential session. Monitor your usage in Settings → Usage.