Last updated: June 2026

Claude Code Sub-AgentsConfigure, Use, and Fan Out in Parallel

Claude Code sub-agents are specialized AI assistants that run in their own context window with their own system prompt, tool access, and permissions. You define them as Markdown files with YAML frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (personal). Claude delegates a matching task to the sub-agent, which works independently and returns only a summary, keeping verbose output out of your main conversation. You can run several in parallel for independent work.

This is the part of Claude Code that turns it from a single assistant into a team. Here is exactly how to configure sub-agents and use them well.

Create One Now Full Claude Code Guide

What Are Sub-Agents in Claude Code?

A sub-agent is a specialized assistant that Claude Code spawns to handle one type of task. It runs in its own context window with a custom system prompt, its own tool access, and independent permissions. When your request matches a sub-agent's description, Claude hands the work over. The sub-agent does the work in isolation and returns only a summary to your main conversation.

The reason this matters is context. A side task like running the full test suite, fetching three pages of API docs, or grepping a large codebase produces output you will never read again. If that lands in your main conversation, it crowds out the work you actually care about. A sub-agent absorbs that output in its own window and returns the one paragraph you need.

Claude Code ships with built-in sub-agents you will see working automatically: Explore (a fast, read-only Haiku agent for searching code), Plan (read-only research during plan mode), and general-purpose (full tools for multi-step work). On top of those, you define your own.

Sub-agent vs skill vs slash command, in one line each:

Sub-agent: isolated context, returns a summary. Best for verbose, self-contained work.
Skill: reusable workflow that runs in your current context. See Claude Code Skills.
Slash command: a saved prompt you trigger by hand.

When Should You Use a Sub-Agent?

Reach for a sub-agent when a task is self-contained and would otherwise flood your main context. Use the main conversation when the work needs frequent back-and-forth.

Use a sub-agent when

The task produces verbose output you do not need (test logs, doc dumps, search results).
You want to enforce tool restrictions, for example a reviewer that cannot write files.
The work is self-contained and can return a clean summary.
You want to run several independent investigations at once.

Stay in the main conversation when

The task needs frequent iterative refinement.
Multiple phases share significant context (plan, build, test).
You are making a quick, targeted change.
Latency matters. A sub-agent starts fresh and needs time to gather context.

How to Create a Claude Code Sub-Agent

There are two routes. Use the /agents command for guided setup, or write the file by hand for full control.

Option 1: the /agents command (recommended)

Run /agents inside Claude Code, switch to the Library tab, choose Create new agent, and pick Personal or Project scope. Select Generate with Claude, describe the agent in plain English, then pick its tools and model. Agents created this way are available immediately, no restart needed.

Option 2: write the file by hand

A sub-agent is a Markdown file with YAML frontmatter, followed by the system prompt in the body. Only name and description are required. Drop it in your project's .claude/agents/ directory, then restart your session to load it.

---
name: code-reviewer
description: Expert code review specialist. Use proactively after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer. When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Report issues by priority: Critical (must fix), Warnings
(should fix), Suggestions (consider). Include a specific fix for each.

Where the files live: .claude/agents/ in your repo root for project sub-agents (commit these so your team shares them), or ~/.claude/agents/ for personal ones available across every project. Identity comes from the name field, not the filename. Keep names unique across the whole tree.

Sub-Agent Frontmatter Fields

These are the fields you will actually reach for. name and description are the only required ones; everything else tightens behavior.

Field	Required	What it does
name	Yes	Unique identifier, lowercase letters and hyphens. This is how the sub-agent is invoked.
description	Yes	Tells Claude when to delegate to this sub-agent. Be specific. Add "use proactively" to encourage automatic delegation.
tools	No	Allowlist of tools the sub-agent can use. Inherits all tools if omitted.
disallowedTools	No	Denylist. Removes tools from the inherited or specified set.
model	No	sonnet, opus, haiku, a full model ID, or inherit. Defaults to inherit. Route cheap tasks to haiku to control cost.
permissionMode	No	default, acceptEdits, plan, dontAsk, or bypassPermissions. Controls how permission prompts are handled.
skills	No	Skills to preload into the sub-agent context at startup. The full skill content is injected.
memory	No	user, project, or local. Gives the sub-agent a persistent memory directory that survives across sessions.
background	No	Set to true to always run this sub-agent as a concurrent background task.
isolation	No	Set to worktree to run the sub-agent in an isolated git worktree, so its edits do not touch your checkout.

Field reference per Anthropic's official sub-agents documentation. The full list also includes mcpServers, hooks, maxTurns, effort, and color.

Restrict Tools So Sub-Agents Cannot Break Things

The single most useful pattern is limiting a sub-agent's tools. A reviewer that has no Write or Edit tool cannot accidentally rewrite your code while it is supposed to be reading it. You have two ways to do this:

Allowlist with tools: the sub-agent gets only what you list.

tools: Read, Grep, Glob, Bash

Denylist with disallowedTools: inherit everything except what you block.

disallowedTools: Write, Edit

If you set both, disallowedTools is applied first, then tools is resolved against what remains. A second lever is model: route cheap, high-volume tasks to haiku and save opus for genuinely hard reasoning. Wondering whether your plan covers heavy sub-agent use? Check the Claude Pro vs Max vs API comparison or run the Claude plan picker.

Parallel Fan-Out: Running Sub-Agents at the Same Time

Sub-agents run in the foreground (blocking) or background (concurrent). Background sub-agents are where the speed comes from: they run while you keep working, using the permissions already granted in the session. For independent work, you can fan several out at once.

PARALLEL RESEARCH

Research the authentication, database, and API modules in parallel using separate sub-agents

Each sub-agent explores its area independently, then Claude synthesizes the findings into one answer.

Three patterns cover most fan-out work:

1. Isolate high-volume output

"Use a sub-agent to run the test suite and report only the failing tests with their error messages." The verbose run stays in the sub-agent; you get the failures.

2. Parallel research

Spawn one sub-agent per independent area. Works best when the paths do not depend on each other.

3. Chain sub-agents in sequence

"Use the code-reviewer sub-agent to find performance issues, then use the optimizer sub-agent to fix them." Each returns results that feed the next.

Failure mode to avoid: fanning out many sub-agents that each return long, detailed results. Every summary lands back in your main conversation, so a wide fan-out of verbose agents can consume as much context as it saved. Keep each sub-agent's return tight, and for sustained parallelism reach for git isolation: worktree so concurrent agents do not fight over the same checkout.

A Real Example: a Cheap, Read-Only Doc Researcher

Here is a sub-agent worth keeping in ~/.claude/agents/. It fetches and summarizes documentation in its own context, runs on Haiku to keep costs down, and is read-only so it can never touch your files.

---
name: doc-researcher
description: Fetches and summarizes external documentation. Use for any task that would flood the main context with web pages or long files.
tools: Read, Grep, Glob, WebFetch, WebSearch
model: haiku
---

You research documentation in your own context and return only
a tight summary with the exact facts, code snippets, and source
URLs the main conversation needs. Never return raw page dumps.

Three things make this work, and they are the same three things that make any sub-agent work:

A specific description. "Use for any task that would flood the main context" tells Claude exactly when to delegate.
A tight tool list. Read, Grep, Glob, WebFetch, WebSearch. No Write or Edit, so it is safe to run unattended.
A model that fits the job. Summarizing docs is not hard reasoning, so Haiku is plenty and far cheaper.

To invoke it explicitly rather than waiting for Claude to delegate, name it in your prompt ("Use the doc-researcher sub-agent to summarize the Stripe webhooks docs") or @-mention it to guarantee it runs.

Frequently Asked Questions

Common questions about Claude Code sub-agents

What is a sub-agent in Claude Code?+

A sub-agent is a specialized AI assistant that Claude Code spawns to handle a specific task in its own context window. It has its own system prompt, its own tool access, and independent permissions. When Claude encounters a task that matches a sub-agent's description, it delegates the work, the sub-agent runs on its own, and only the summary returns to your main conversation. This keeps verbose output (search results, logs, test runs) out of your main context.

Where do Claude Code sub-agent files live?+

Project sub-agents go in .claude/agents/ in your repo root (check them into version control so your team shares them). Personal sub-agents go in ~/.claude/agents/ and are available across all your projects. Both directories are scanned recursively, so you can organize files into subfolders like agents/review/ or agents/research/. Identity comes from the name field in the frontmatter, not the filename or folder path.

How do I create a Claude Code sub-agent?+

Run the /agents command inside Claude Code, choose Library then Create new agent, pick Personal or Project scope, and let Claude generate the config from a plain-English description. Or create the file by hand: a Markdown file with YAML frontmatter (name and description are required) followed by the system prompt in the body. Sub-agents created through /agents take effect immediately; files added on disk require a session restart.

Can Claude Code run sub-agents in parallel?+

Yes. Background sub-agents run concurrently while you keep working, and you can ask Claude to research several independent areas at once (for example: 'Research the auth, database, and API modules in parallel using separate sub-agents'). Each sub-agent explores its area in its own context, then Claude synthesizes the findings. Parallel fan-out works best when the tasks do not depend on each other. Foreground sub-agents, by contrast, block the main conversation until they finish.

What is the difference between a sub-agent and a slash command or skill?+

A sub-agent runs in an isolated context window and returns only a summary, which is ideal for verbose, self-contained work. A skill is a reusable prompt or workflow that runs in your main conversation context, so it shares your existing history. A slash command is a saved prompt you trigger manually. Use a sub-agent when you want isolation and tool restrictions; use a skill when the work needs your current context.

How does Claude decide which sub-agent to use?+

Claude reads the description field of each registered sub-agent and matches it against your request and the current context. A vague description means Claude rarely delegates; a specific one (with phrases like 'use proactively after code changes') makes delegation reliable. You can also force a choice: name the sub-agent in your prompt, @-mention it to guarantee it runs, or launch a whole session as one sub-agent with the --agent flag.

Can a sub-agent use fewer tools than the main session?+

Yes, and you should usually restrict them. Use the tools field as an allowlist (for example 'tools: Read, Grep, Glob, Bash' for a read-only reviewer) or disallowedTools as a denylist (for example 'disallowedTools: Write, Edit' to inherit everything except file writes). A reviewer that cannot edit files cannot accidentally break your codebase. Sub-agents inherit all tools by default if you omit both fields.

Can a Claude Code sub-agent spawn its own sub-agents?+

Yes, as of Claude Code v2.1.172, a sub-agent can spawn nested sub-agents when its delegated task itself splits into parallel subtasks (for example, a reviewer that dispatches a verifier per finding). The intermediate output never reaches your main conversation; only the top-level sub-agent's summary returns. Background sub-agents stop spawning at depth five to prevent runaway concurrent trees.

Official Resources

↗Claude Code Sub-Agents Docs ↗Claude Code Documentation

Keep Going With Claude Code

Sub-agents are one piece of the extension stack. Start with the hub guide, then go deep on each part.

Paste a sub-agent description into the free grader and get scored feedback on what will make it delegate reliably.