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:

code
.agents/
  subagents/
    code-reviewer.md
    test-writer.md
    documentation-writer.md

Each file defines a specialized subagent persona:

markdown
---
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 added

Communication between subagents

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.

Cost consideration

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.