# Claude Code Subagents

> Source: https://aiwiki.ai/wiki/claude_code_subagents
> Updated: 2026-05-16
> Categories: AI Agents, Anthropic, Developer Tools
> From AI Wiki (https://aiwiki.ai), a free encyclopedia of artificial intelligence. Quote with attribution.

**Claude Code subagents** (also **sub-agents**) are a feature of [Anthropic](/wiki/anthropic)'s [Claude Code](/wiki/claude_code) command-line tool that lets the main Claude conversation delegate side tasks to specialized child assistants. Each subagent runs in its own [context window](/wiki/context_window) with a custom system prompt, an independent set of permitted tools, and its own permission mode. When the main agent encounters work matching a subagent's description, it spawns the subagent, which does the work in isolation and returns only its final summary. The feature rolled out progressively in July 2025, with some early users reporting access on July 5 and a broader public announcement around July 25, 2025.[1][2][3]

Subagents address a recurring frustration in long Claude Code sessions: a single thread fills up with verbose tool output (test logs, file dumps, search results) that the main task does not need to keep in view. Routing that work to a subagent lets the parent receive only a short summary. Subagents are Markdown files with YAML frontmatter, stored under `.claude/agents/` for a project or `~/.claude/agents/` for personal use, and can be committed to version control for sharing.[1][3]

## Quick reference

| Attribute | Value |
|---|---|
| Developed by | [Anthropic](/wiki/anthropic) |
| Parent product | [Claude Code](/wiki/claude_code) |
| Public rollout | July 2025 (broader announcement July 25, 2025) |
| Configuration format | Markdown files with YAML frontmatter |
| Project location | `.claude/agents/` (version-controlled) |
| User location | `~/.claude/agents/` (personal, all projects) |
| Required frontmatter fields | `name`, `description` |
| Built-in subagents | Explore, Plan, general-purpose, statusline-setup, claude-code-guide |
| Management command | `/agents` |
| Explicit invocation | `@agent-<name>` mention, natural language, `--agent <name>` flag |
| Tool isolation | `tools` allowlist, `disallowedTools` denylist |
| Permission modes | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan` |
| Nesting | Subagents cannot spawn other subagents |
| Related features | [Claude Skills](/wiki/claude_skills), agent teams, background agents, [Model Context Protocol](/wiki/mcp) |

## Background

Claude Code is Anthropic's official command-line coding tool, released publicly in May 2025 alongside the Claude 4 model family. Its design favors a single autonomous agent that drives the terminal: the developer states a goal, Claude reads files, runs shell commands, edits source, and reports back. The single-thread design works well for short tasks but produces context pressure on long sessions, because each verbose tool result competes with the actual instructions for space in the [context window](/wiki/context_window).

The earlier Anthropic primitives for managing context were the [Model Context Protocol](/wiki/mcp) and prompt caching. Neither addressed the case where a developer wanted Claude to run an exploratory side task that should not contaminate the main thread. Subagents fill that gap by giving Claude a way to fork off a child conversation with its own fresh context, run a tightly scoped job, and return only the summary.

The feature shipped after Anthropic's May 2025 developer toolkit update and ahead of the [Claude Skills](/wiki/claude_skills) standard, which arrived in October 2025. Subagents and Skills are complementary: subagents create context isolation, Skills package reusable prompt and reference material.[4][7]

## How subagents work

A subagent is a child Claude session spawned from the main conversation. The lifecycle has four phases:

1. **Trigger.** The user types a natural-language prompt that names a subagent, uses `@agent-<name>` to pick one explicitly, or asks Claude to do something that matches an installed subagent's `description` field. Claude reads its list of registered subagents and decides whether delegation makes sense.
2. **Isolation.** Claude creates a new context window for the child. The subagent receives only its own system prompt (from the YAML frontmatter and the Markdown body) plus minimal environment details such as the current working directory. It does not see the parent's conversation history.
3. **Execution.** The subagent works independently with the tools it is allowed to use, runs whatever commands its prompt directs, and stays within its own context window until the task finishes or `maxTurns` is reached.
4. **Summary return.** When the subagent finishes, only its final message returns to the parent. Every intermediate tool call, search result, and log line stays inside the subagent's transcript.[1]

Claude Code stores subagent transcripts separately under `~/.claude/projects/{project}/{sessionId}/subagents/` as `agent-{agentId}.jsonl` files. The transcripts are persisted, so a developer can later resume an individual subagent without restarting. Subagent transcripts also survive auto-compaction of the parent conversation.[1]

### Tool isolation

By default, a subagent inherits every tool the main conversation has, including [MCP](/wiki/mcp) tools. Authors can narrow that surface in two ways:

- The `tools` field declares an explicit allowlist. Anything not in the list is removed.
- The `disallowedTools` field declares a denylist. Listed tools are removed; everything else is inherited.

If both fields are present, `disallowedTools` is evaluated first, then `tools` narrows the remaining pool. Tool isolation is what makes a `code-reviewer` subagent genuinely read-only: by listing only `Read, Grep, Glob, Bash` in `tools`, it cannot accidentally edit files even when asked.[1]

### Permission inheritance

Subagents inherit the parent's permission context but can override the permission mode through `permissionMode`. If the parent is using `bypassPermissions` or `acceptEdits`, that mode takes precedence and the subagent cannot loosen it back. If the parent is in auto mode, the subagent's `permissionMode` is ignored entirely. A child cannot escalate above the parent's permission posture.[1]

### Nesting limitation

A subagent cannot spawn another subagent. The restriction prevents runaway nesting and recursive token explosion. Developers who need deeper hierarchies use the agent teams feature, which gives each worker an independent context that can communicate with siblings, or chain subagents in sequence from the main conversation.[1]

## Configuration

Subagents are Markdown files with YAML frontmatter. The minimum file is short: a name, a description, and a system prompt body.

```
---
name: code-reviewer
description: Reviews code for quality and best practices. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer ensuring high standards of code quality
and security. When invoked, run git diff to see recent changes, then
review modified files for clarity, security, error handling, and tests.
Report issues grouped by severity (critical, warning, suggestion) with
specific fixes.
```

The body replaces the default Claude Code system prompt for the subagent. Anthropic notes that subagents receive only this system prompt plus basic environment metadata, not the long default Claude Code system prompt the main agent uses.[1]

### Supported frontmatter fields

The frontmatter is parsed as YAML. Only `name` and `description` are required.[1]

| Field | Required | Purpose |
|---|---|---|
| `name` | Yes | Unique identifier (lowercase, hyphens). The filename does not have to match. Hooks receive this as `agent_type`. |
| `description` | Yes | Tells Claude when to delegate to this subagent. The most important authoring decision. |
| `tools` | No | Allowlist of tools. Inherits all parent tools if omitted. |
| `disallowedTools` | No | Denylist applied before the allowlist. |
| `model` | No | `sonnet`, `opus`, `haiku`, a full model ID, or `inherit`. Defaults to `inherit`. |
| `permissionMode` | No | `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, or `plan`. |
| `maxTurns` | No | Caps agentic turns before the subagent stops. |
| `skills` | No | [Claude Skills](/wiki/claude_skills) to preload into the subagent's context at startup. |
| `mcpServers` | No | [MCP](/wiki/mcp) servers scoped to this subagent. |
| `hooks` | No | Lifecycle hooks (`PreToolUse`, `PostToolUse`, `Stop`) scoped to this subagent. |
| `memory` | No | Persistent memory scope: `user`, `project`, or `local`. |
| `background` | No | Set `true` to always run this subagent in the background. |
| `effort` | No | Effort level override: `low`, `medium`, `high`, `xhigh`, or `max`. |
| `isolation` | No | Set to `worktree` to spawn the subagent in a temporary git worktree. |
| `color` | No | Display color for the subagent in the task list. |
| `initialPrompt` | No | Auto-submitted as the first user turn when the subagent runs as the main session. |

### Scope and precedence

Subagents can be stored in five locations, and Claude Code resolves name conflicts using a fixed precedence order. Higher rows beat lower rows.[1]

| Location | Scope | Priority | How to create |
|---|---|---|---|
| Managed settings directory | Organization-wide | 1 (highest) | Deployed via enterprise managed settings |
| `--agents` CLI flag | Current session only | 2 | JSON passed at launch |
| `.claude/agents/` | Current project | 3 | Interactive `/agents` or manual file |
| `~/.claude/agents/` | All your projects | 4 | Interactive `/agents` or manual file |
| Plugin's `agents/` directory | Wherever the plugin is enabled | 5 (lowest) | Installed with [plugins](/wiki/plugin) |

Project subagents are designed to be checked into version control. User subagents follow the developer across repositories. CLI-defined subagents passed through `--agents` exist only for that session, useful for automation scripts or one-off experiments. For security reasons, plugin subagents cannot use the `hooks`, `mcpServers`, or `permissionMode` fields.[1]

Claude Code scans `.claude/agents/` and `~/.claude/agents/` recursively, so a team can organize agent files into subfolders such as `agents/review/` or `agents/research/`. Identity comes from the `name` field, not the path. Plugin paths behave differently: a file at `agents/review/security.md` inside a plugin called `my-plugin` registers as `my-plugin:review:security`.[1]

### The /agents command

The most common way to author subagents is the interactive `/agents` command. It opens a tabbed UI with two views: Running (live subagents, with controls to open or stop them) and Library (create, edit, delete, or view definitions). The Library tab supports a Generate with Claude flow that drafts the frontmatter and system prompt from a natural-language description, which Anthropic recommends as the starting point.[1][3]

During guided creation, the user picks a scope, allowed tools, model, color, and optionally a memory scope. Saving through the UI makes the agent available immediately without restarting. Manual file edits currently require a session restart.[1]

## Built-in subagents

Claude Code ships several built-in subagents that the main agent delegates to automatically when appropriate. Each inherits the parent's permissions, then layers on additional tool restrictions for its specialty.[1]

| Built-in subagent | Model | Tool surface | Purpose |
|---|---|---|---|
| Explore | Haiku | Read-only | Fast file discovery, code search, codebase exploration. Supports quick, medium, and very thorough levels. |
| Plan | Inherits | Read-only | Codebase research during plan mode. Prevents nesting while gathering context. |
| general-purpose | Inherits | All tools | Complex multi-step tasks that mix exploration and modification. |
| statusline-setup | Sonnet | Statusline tooling | Configures the status line when the user runs `/statusline`. |
| claude-code-guide | Haiku | Documentation tools | Answers questions about Claude Code itself. |

Explore is the workhorse of the built-in set. When the user asks Claude to find every reference to a function across a large codebase, the main agent typically delegates to Explore so the search output stays out of the parent context. Explore returns a compact summary with file paths and short snippets. The Plan subagent plays a similar role inside plan mode. Users can disable any built-in subagent through the `permissions.deny` list in settings (`"Agent(Explore)"`) or via the `--disallowedTools "Agent(Explore)"` flag.[1]

## Custom subagents

Beyond writing files by hand, there are four authoring paths:

- Run `/agents` and pick Generate with Claude (Anthropic's recommended start).
- Run `/agents` and pick Create new agent to fill in the fields manually.
- Place a Markdown file in `.claude/agents/` or `~/.claude/agents/` and restart the session.
- Pass a `--agents` JSON blob when launching `claude`.

A team typically ends up with a small collection of focused subagents committed to the repository: a reviewer, a debugger, an API tester, perhaps a documentation writer. Anthropic's own examples include a `code-reviewer` with read-only tools and a checklist body, a `debugger` with Edit access, a `data-scientist` that runs SQL through Bash, and a `db-reader` that uses a `PreToolUse` hook to block any non-SELECT query.[1]

The `description` field is the most important authoring decision. Anthropic's guidance: include phrases like "use proactively" or "use immediately after" to encourage automatic delegation. A vague description like "helps with code" will rarely fire; a specific one like "Expert code reviewer. Use proactively after code changes" delegates reliably.[1][3]

## Use cases

The pattern is always the same: take a self-contained task that generates verbose intermediate output, push it into a subagent, keep the main thread focused on the higher-level goal.

| Use case | What the subagent does | Typical tool surface | Why isolate |
|---|---|---|---|
| Code review | Reads diffs and reports quality, security, and style issues | Read, Grep, Glob, Bash | Long diffs and many file reads would clog the main context |
| Debugging | Reproduces a bug, isolates root cause, applies a minimal fix | Read, Edit, Bash, Grep | Verbose logs and stack traces stay in the subagent |
| Security audit | Scans for OWASP vulnerabilities, exposed secrets, or policy violations | Read, Grep, Bash | The audit report is short; the scan output is long |
| API test generation | Writes and runs tests for HTTP endpoints | Read, Write, Bash, Playwright via MCP | Test scaffolding noise stays isolated |
| Database analysis | Runs read-only SQL queries against production data | Bash plus query validator hook | Hooks enforce that only SELECT statements run |
| Documentation lookup | Fetches and summarizes external docs | Read, WebFetch, Bash | Large pages flood context if read directly |
| Migration specialist | Applies repetitive refactors across many files | Read, Edit, Grep, Glob | Hundreds of edits collapsed into a single summary |
| Test runner | Executes the full suite and reports failures only | Bash, Read | Pass output is huge; failures are the only signal needed |
| Codebase research | Surveys an unfamiliar repository | Read-only (Explore is the built-in fit) | Keeps search results out of the parent |
| Parallel research | Investigates auth, database, and API modules at once | Read, Grep, Glob | Each subagent works in its own context, then Claude merges findings |

Anthropic's example library showcases two recurring patterns. The first is the read-only reviewer: a subagent restricted to `Read, Grep, Glob, Bash` that runs `git diff` and reports findings without modifying source. The second is the validated executor: a subagent gets a permissive tool (typically `Bash`) but a `PreToolUse` hook script blocks any command that fails a pattern check. The database query validator example uses this pattern to ensure only SELECT statements reach the database.[1]

### Common interaction patterns

The documentation calls out three multi-subagent patterns:[1]

- **Isolate high-volume operations.** Run tests or fetch documentation in a subagent. The verbose output stays in its own context and only the summary returns.
- **Run parallel research.** Spawn several subagents to investigate independent areas of a codebase. Each works in its own context, then the main agent synthesizes findings.
- **Chain subagents.** Use a reviewer to find issues, then an optimizer to fix them. The main agent passes the relevant context from one to the next.

The biggest pitfall with multi-subagent fan-out is the same trick that makes fan-out useful: each summary still returns to the parent, and several large summaries can consume serious context. For sustained parallelism beyond a single session, Anthropic suggests agent teams.[1]

## Best practices

Anthropic's documentation and the developer community have converged on a small set of guidelines:[1][3]

- **Design focused subagents.** Each one should excel at one task. A subagent that tries to do everything gets delegated to for the wrong reasons.
- **Write detailed descriptions.** Phrases like "use proactively" or "use immediately after" are known triggers for automatic delegation.
- **Limit tool access.** Grant only the tools the subagent needs. A read-only reviewer should have only read-only tools.
- **Pick the right model.** Haiku for fast triage; Sonnet for code review or analysis; Opus for deep reasoning.
- **Check project subagents into version control.** Files in `.claude/agents/` are sharable across the team.
- **Iterate from a Claude-generated draft.** Use Generate with Claude as a starting point and refine by hand.
- **Use hooks for conditional rules.** When `tools` allowlists are not granular enough, a `PreToolUse` hook script can validate individual commands.
- **Enable persistent memory selectively.** `project` scope for repository-specific knowledge, `user` for knowledge that should follow the developer everywhere.
- **Mind the context cost.** Even though intermediate output is hidden, the final summary still lands in the parent. Many subagents that each return a long summary can eat the main context.

## Comparison to other agentic coding tools

Most AI coding tools shipped some form of multi-agent delegation by mid-2026, but the implementations diverge in important ways. The table compares Claude Code subagents to similar features in [Cursor](/wiki/cursor), [OpenAI Codex CLI](/wiki/codex_cli), and Cline.

| Aspect | Claude Code subagents | Cursor background agents | OpenAI Codex CLI | Cline |
|---|---|---|---|---|
| Vendor | [Anthropic](/wiki/anthropic) | Cursor (Anysphere) | [OpenAI](/wiki/openai) | Cline (open source) |
| Primary surface | Terminal CLI | IDE plus cloud | Terminal CLI | VS Code extension |
| Delegation model | In-session subagent with own context | Cloud VM provisioned per agent | Single-agent loop with task queuing | Single-agent loop with plan/act split |
| Configuration | Markdown plus YAML in `.claude/agents/` | Cursor settings and `.cursor/rules` | CLI flags and `AGENTS.md` | `.clinerules` |
| Tool isolation per agent | Yes, `tools` and `disallowedTools` per subagent | Per-agent permissions and approvals | Tools applied at session level | Tools applied at session level |
| Parallelism | Multiple subagents per session | Parallel cloud VMs | Sequential by default | Sequential by default |
| Version control sharing | Yes, project subagents committed to repo | Yes, rules committed to repo | Yes via `AGENTS.md` | Yes via `.clinerules` |
| Context model | Fresh context per subagent | Each agent has its own VM and context | Shared session context | Shared session context |
| Built-in delegates | Explore, Plan, general-purpose, others | None | None | None |
| Compatibility with [Claude Skills](/wiki/claude_skills) | Yes, via `skills` frontmatter | Yes, since the Agent Skills open standard | Yes, since the Agent Skills open standard | Yes, since the Agent Skills open standard |

Cursor favors heavy cloud isolation: each background agent runs on its own VM with a full filesystem and terminal. Claude Code subagents are lighter-weight, sharing the user's local machine but separating the context window. The two designs serve different scenarios: Cursor's background agents work well for tasks that run for hours; Claude Code subagents work well for delegating side jobs inside a single interactive session.[5][6]

[Codex CLI](/wiki/codex_cli) ships an `AGENTS.md` pattern that defines repository-wide instructions and per-agent prompts, but it does not separate context per delegated task. Instead it relies on heavy compaction and a shared workspace. Cline, the open-source VS Code extension, separates planning and execution into two modes but does not isolate either. Among major tools, only Claude Code ships the specific pattern of named subagent files with their own tool allowlists.[5]

## Relationship to other Anthropic features

Subagents are one of several context-management primitives Anthropic shipped in 2025 and 2026:

| Feature | Released | What it does | When to reach for it |
|---|---|---|---|
| Claude Code subagents | July 2025 | Spawn a child Claude inside the current session with its own context and tools | Side task that would clog the main thread |
| [Claude Skills](/wiki/claude_skills) | October 16, 2025 | Reusable procedural knowledge loaded on demand from Markdown folders | Repeated workflows that need standing instructions |
| Background agents (Agent View) | May 11, 2026 (research preview) | Manage long-running concurrent Claude Code sessions from one list | Tasks that exceed a single session |
| Agent teams | Early 2026 (experimental) | Multiple workers with their own context, able to message each other | Cross-domain coordination beyond what one subagent can handle |
| [Model Context Protocol](/wiki/mcp) | November 2024 (open standard) | Expose external tools and data sources to any agent over a defined protocol | Connect Claude to systems and APIs |
| Forked subagents | v2.1.117 (experimental, opt-in via env var) | Subagent that inherits the entire parent conversation instead of starting fresh | Side tasks that need full context but should not pollute the main thread |

Forked subagents are a more recent variant. A fork inherits the full conversation history of the parent at the moment of spawn, so it sees the same system prompt, tools, and message history. Its tool calls still stay out of the parent context. Anthropic describes forks as the right pick when a named subagent would need too much background to be useful. Forks are gated behind an environment variable as of mid-2026 and cannot spawn further forks.[1]

Anthropic's documentation steers developers to pick the smallest primitive that solves the problem: a Skill is cheaper than a subagent, a subagent is cheaper than an agent team.[1][4]

## Reception

Reaction to the July 2025 launch was broadly positive. WinBuzzer described the feature as a way to "transform a single AI assistant into a powerful, customizable team of specialized experts" and credited subagents with solving the "context pollution" problem that had been a recurring complaint about long Claude Code sessions.[2][3] Tech press coverage emphasized the combination of simplicity (a Markdown file with frontmatter) and power (independent context, scoped tools, version-controllable definitions).

Developer writeups on Dev.to and AntStack tracked the feature's rapid evolution. AntStack's field guide drew a clean distinction: "Subagents are child Claude instances for parallelization, while Skills are reusable instruction packages." Subagents "only report back to the parent," whereas agent teams can message each other directly. The guide recommended starting with subagents and upgrading to teams only when inter-agent communication is required.[4]

In the year after launch, Anthropic refined the feature in nearly every Claude Code release. The changelog through May 2026 lists case-insensitive `subagent_type` matching, fixes to skill discovery inside subagents, forked subagent support, isolation modes including git worktrees, dedicated request headers (`x-claude-code-agent-id` and `x-claude-code-parent-agent-id`) for API tracing, and tighter integration with the Agent View introduced in v2.1.139 on May 11, 2026. Agent View surfaces a list of every Claude Code session so a developer can manage many parallel agents from one place.[8]

CEO Dario Amodei summarized the design philosophy when he told reporters that Anthropic is "heading to a world where a human developer can manage a fleet of agents, but continued human involvement is going to be important for the quality control."[3]

Not all reactions were uncritical. Several writeups flagged the same trap Anthropic itself warns about: many subagents that each return long summaries can blow out the main context as fast as inlining the work would. Developers also note that subagents add latency, because each one starts fresh and may need time to gather its own context. The official guidance: use the main conversation for quick targeted changes; reserve subagents for self-contained work that produces verbose output.[1]

## See also

- [Anthropic](/wiki/anthropic)
- [Claude Code](/wiki/claude_code)
- [Claude Skills](/wiki/claude_skills)
- [Claude (AI)](/wiki/claude_ai)
- [Claude Agent SDK](/wiki/claude_agent_sdk)
- [Model Context Protocol](/wiki/mcp)
- [Cursor](/wiki/cursor)
- [OpenAI Codex CLI](/wiki/codex_cli)
- [Cline](/wiki/cline)
- [Context window](/wiki/context_window)
- [System prompt](/wiki/system_prompt)
- [Tool use (artificial intelligence)](/wiki/tool_use)
- [AI agent](/wiki/ai_agent)
- [GitHub Copilot](/wiki/github_copilot)
- [Plugin](/wiki/plugin)
- [Slash command](/wiki/slash_command)

## References

1. "Create custom subagents." Claude Code Documentation. https://code.claude.com/docs/en/sub-agents (accessed May 2026).
2. "Anthropic Unveils Subagent Framework for Claude Code AI Development Tool." Blockchain.News. July 2025. https://blockchain.news/news/anthropic-claude-code-subagents-developer-guide
3. "Anthropic Rolls Out Claude Code 'Sub-Agents' to Streamline Complex AI Workflows." WinBuzzer. July 26, 2025. https://winbuzzer.com/2025/07/26/anthropic-rolls-out-sub-agents-for-claude-code-to-streamline-complex-ai-workflows-xcxwbn/
4. "Claude Agents, Subagents, Agent Teams, Skills and MCP: A Developer's Field Guide." AntStack. https://www.antstack.com/blog/claude-agents-subagents-agent-teams-skills-and-mcp-a-developer-s-field-guide/ (accessed May 2026).
5. "Anthropic Shows How to Scale Claude Code with Subagents and MCP." WinBuzzer. March 24, 2026. https://winbuzzer.com/2026/03/24/anthropic-claude-code-subagent-mcp-advanced-patterns-xcxwbn/
6. "Comparing Cursor Agent to Claude Code." DoltHub Blog. August 15, 2025. https://www.dolthub.com/blog/2025-08-15-cursor-agent-vs-claude-code/
7. "Enabling Claude Code to work more autonomously." Anthropic. September 29, 2025. https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously
8. "Changelog." Claude Code Documentation. https://code.claude.com/docs/en/changelog (accessed May 2026).