Reference: Agent tool
Subagents are specialized Claude instances that the main agent can spawn to handle tasks in parallel or in isolation. Each subagent runs with its own context window, returns a single result, and then terminates.
| Scenario | Benefit |
|---|---|
| Independent tasks (e.g. search + test run) | Execute in parallel, saving time |
| Large search results | Protect the main context from noise |
| Isolated file changes | Work in a separate git worktree |
| Specialized work | Use a purpose-built agent type |
| Type | Best for |
|---|---|
general-purpose |
Multi-step research, code search, complex tasks |
Explore |
Fast codebase exploration (read-only) |
Plan |
Designing implementation strategies |
claude-code-guide |
Questions about Claude Code features or the API |
- Context isolation — the subagent does not share the parent's conversation history; give it all the context it needs in the prompt.
- Single result — the subagent returns one message; the parent decides what to show the user.
- Background mode — use
run_in_background: truefor fire-and-forget tasks; the parent is notified on completion. - Worktree isolation — use
isolation: "worktree"to give the subagent its own git branch; the worktree is cleaned up automatically if no changes are made.
- Simple, directed searches — use
GloborGrepdirectly instead. - Reading 2–3 specific files — use the
Readtool. - Tasks that depend on results the parent already has.
Prefer parallel subagent calls when tasks are independent. Avoid duplicating work the subagent is already doing — if you delegate research, don't repeat the same searches yourself.