Claude Code Subagents
Last reviewed
May 16, 2026
Sources
8 citations
Review status
Source-backed
Revision
v1 ยท 4,000 words
Improve this article
Add missing citations, update stale details, or suggest a clearer explanation.
Suggest edit
CtrlK
Last reviewed
May 16, 2026
Sources
8 citations
Review status
Source-backed
Revision
v1 ยท 4,000 words
Add missing citations, update stale details, or suggest a clearer explanation.
Claude Code subagents (also sub-agents) are a feature of Anthropic's 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 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]
| Attribute | Value |
|---|---|
| Developed by | Anthropic |
| Parent product | 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, agent teams, background agents, Model Context Protocol |
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.
The earlier Anthropic primitives for managing context were the Model Context Protocol 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 standard, which arrived in October 2025. Subagents and Skills are complementary: subagents create context isolation, Skills package reusable prompt and reference material.[4][7]
A subagent is a child Claude session spawned from the main conversation. The lifecycle has four phases:
@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.maxTurns is reached.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]
By default, a subagent inherits every tool the main conversation has, including MCP tools. Authors can narrow that surface in two ways:
tools field declares an explicit allowlist. Anything not in the list is removed.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]
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]
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]
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]
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 to preload into the subagent's context at startup. |
mcpServers | No | 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. |
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 |
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 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]
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]
Beyond writing files by hand, there are four authoring paths:
/agents and pick Generate with Claude (Anthropic's recommended start)./agents and pick Create new agent to fill in the fields manually..claude/agents/ or ~/.claude/agents/ and restart the session.--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]
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]
The documentation calls out three multi-subagent patterns:[1]
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]
Anthropic's documentation and the developer community have converged on a small set of guidelines:[1][3]
.claude/agents/ are sharable across the team.tools allowlists are not granular enough, a PreToolUse hook script can validate individual commands.project scope for repository-specific knowledge, user for knowledge that should follow the developer everywhere.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, OpenAI Codex CLI, and Cline.
| Aspect | Claude Code subagents | Cursor background agents | OpenAI Codex CLI | Cline |
|---|---|---|---|---|
| Vendor | Anthropic | Cursor (Anysphere) | 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 | 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 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]
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 | 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 | 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]
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]