> ## Documentation Index
> Fetch the complete documentation index at: https://agentic.proxify.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagent Patterns

> When and how to use subagents to parallelize work while keeping your main context clean.

<Note>**You'll learn:** when subagents help vs. hurt, how to keep your main context clean, and how to handle permission routing.</Note>

<Tip>**Official reference** — The [official sub-agents docs](https://docs.anthropic.com/en/docs/claude-code/sub-agents) cover built-in agent types, the Agent tool parameters, custom agent frontmatter fields, and permission modes. This page adds the decision framework for when subagents help vs. hurt.</Tip>

## What Are Subagents?

Claude Code can spawn lightweight agents to handle tasks in parallel. These subagents run independently, do their work, and report back — while your main conversation stays focused.

You don't need special syntax. Just tell Claude:

* "Use subagents for this"
* "Parallelize this work across subagents"
* "Spin up agents to handle each file separately"

## Context Hygiene

The main value of subagents is **keeping your primary context clean**. Every file read, every exploration, every dead end consumes context. Subagents take that cost on themselves and return only the results.

Offload to subagents:

* Broad codebase exploration ("find all the places we handle authentication")
* Research across multiple files or directories
* File scanning and pattern matching
* Independent analysis tasks

Keep in your main context:

* Decision-making and architecture
* Sequential implementation steps
* Anything that requires the full picture

The built-in **Explore agent** is the easiest win — it runs on Haiku with read-only access for broad codebase exploration without polluting your main context.

## When Subagents Help

| Scenario                                 | Why subagents work                             |
| ---------------------------------------- | ---------------------------------------------- |
| Reading 10+ files to understand a system | Each subagent reads a subset, reports findings |
| Analyzing independent modules            | No dependencies between analysis tasks         |
| Running tests across different areas     | Each test suite runs in isolation              |
| Researching multiple approaches          | Explore options in parallel, compare results   |
| Large refactors across many files        | Each subagent handles a subset of files        |

## When They Don't

| Scenario                                        | Why subagents hurt                       |
| ----------------------------------------------- | ---------------------------------------- |
| Sequential decisions (step 2 depends on step 1) | Subagents can't coordinate mid-task      |
| Tasks requiring full project context            | Each subagent only sees what you give it |
| Small, focused tasks                            | Overhead of spawning isn't worth it      |
| Tasks requiring user approval at each step      | Subagents run autonomously               |

## Permission Routing

You can set up a hook that routes permission requests to a lighter model (like Haiku) for auto-approval of safe operations. This keeps subagents running without interrupting your main conversation for every file read or bash command.

Without permission routing, you'll get interrupted for every subagent action — which defeats the purpose of parallelization.

<Note>**Auto-routing reliability:** Claude reads each agent's `description` to decide when to delegate, but auto-routing to custom agents remains unreliable. Making descriptions specific and action-oriented helps. The most reliable trigger is explicit instruction: "Use the security-reviewer agent to audit this module."</Note>

<Tip>Start with exploration tasks — they're the easiest win. For advanced multi-agent coordination, see [Orchestration Patterns](orchestration-patterns/) and [Agent Teams](agent-teams/).</Tip>

***