Sub-agents
Sub-agents are specialized, isolated AI worker instances that Claude Code can spawn to handle specific tasks. Each sub-agent runs in its own separate context window, with its own system prompt and a restricted set of tools, so it stays focused on a narrow job without cluttering the main conversation. The main (parent) agent orchestrates which sub-agent to use and when, then receives back a concise summary rather than all the raw intermediate output.
Sub-agents are defined in Markdown files with YAML frontmatter and can be scoped to a single project (`.claude/agents/`) or shared across all projects (`~/.claude/agents/`). Claude Code ships with several built-in sub-agents — Explore, Plan, and a general-purpose agent — and you can create unlimited custom ones.
The key benefits are context preservation (verbose tool output stays inside the sub-agent's window), tool-level security (a read-only reviewer can never accidentally overwrite files), cost control (route cheap tasks to a smaller model), and parallelism (multiple sub-agents can run at the same time, dramatically speeding up complex workflows).
When you’d use it
- ◆Codebase exploration without context pollution — You ask Claude to find where authentication logic lives in a 300-file repo. Instead of dumping thousands of lines of grep output into your main chat, Claude delegates to the built-in Explore sub-agent, which searches the codebase in its own context window and returns only a short summary of the relevant files and functions.
- ◆Read-only security or quality review — A custom code-reviewer sub-agent is granted only Read, Grep, and Glob tools — no Edit or Write. When asked to review a pull request, it can analyze every changed file but is structurally prevented from modifying anything, making accidental overwrites impossible.
- ◆Parallel batch processing — You need to migrate 50 database queries from synchronous to asynchronous I/O. Ten async-migrator sub-agents run concurrently, each handling a separate module, running tests, and submitting a PR. The main session shows a live progress summary instead of serializing the work.
- ◆Cost-optimized routing — A workflow routes simple file-search tasks to a sub-agent configured to use a smaller, cheaper model (e.g., Haiku), while reserving the more capable and expensive model for the main orchestration and complex reasoning steps.
- ◆Domain-specialized assistants reused across projects — A security-auditor sub-agent stored at ~/.claude/agents/security-auditor.md encodes OWASP best practices in its system prompt and is available in every project. Any team member can invoke it consistently without re-explaining the rules each session.
What changed recently
- ◆2026-01-28 — The Claude Code SDK was renamed to the Claude Agent SDK. SDK support for sub-agents and hooks was released, giving programmatic access to the same tools, agent loop, and context management that power Claude Code interactive sub-agents.
- ◆2026-04-15 — Worktree isolation for sub-agents became available. Adding 'isolation: worktree' to a sub-agent's frontmatter launches it in an isolated git worktree, enabling safe parallel agents that cannot overwrite each other's changes.
- ◆2026-06-15 — Claude Agent SDK and 'claude -p' usage was separated from Claude plan usage limits. Starting this date, SDK usage no longer counts against interactive plan limits. Eligible Pro, Max, Team, and Enterprise users can claim a separate monthly Agent SDK credit that refreshes with the billing cycle.
This is the short version
The full chapter has three worked examples, the common pitfalls, and the workflow that makes it pay — plus the other 84 features, kept current.
Get Claude Master — $97 →