Claude Code Subagents

Claude Code subagents (also sub-agents) are specialized AI assistants that Claude Code, Anthropic's command-line coding tool, can delegate specific tasks to. Each subagent runs in its own context window with a custom system prompt, a specific set of allowed tools, and independent permissions, so it can handle a side task (searching a codebase, running tests, reviewing a diff) without filling the main conversation with output the primary task will never reference again. Anthropic's documentation defines them plainly: "Subagents are specialized AI assistants that handle specific types of tasks," and "Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions."^[1] When Claude encounters a task that matches a subagent's description, it delegates to that subagent, which works independently 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 are defined as Markdown files with YAML frontmatter (a name, a description, and an optional tools, model, and more), stored under .claude/agents/ for a single project or ~/.claude/agents/ for personal use across all projects, and project-level files can be committed to version control so a whole team shares them.^[1] They 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.^[1][3]

Quick reference

Scroll sideways for more →

What are Claude Code subagents?

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.

A subagent is Claude Code's answer to that pressure. Anthropic frames the decision concretely: "Use one when a side task would flood your main conversation with search results, logs, or file contents you won't reference again: the subagent does that work in its own context and returns only the summary."^[1] The official benefits list is five items long. Subagents help you "preserve context" by keeping exploration and implementation out of the main conversation, "enforce constraints" by limiting which tools a subagent can use, "reuse configurations" across projects with user-level subagents, "specialize behavior" with focused system prompts for specific domains, and "control costs" by routing tasks to faster, cheaper models like Haiku.^[1]

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 spawn 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]

How do 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. Anthropic's guidance is direct: "Claude uses each subagent's description to decide when to delegate tasks. When you create a subagent, write a clear description so Claude knows when to use it."^[1]
2. Isolation. Claude creates a new context window for the child. Per the documentation, "Each subagent starts with a fresh, isolated context window. It doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read."^[1] 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.
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; as the documentation puts it, "when the main conversation compacts, subagent transcripts are unaffected. They're stored in separate files."^[1] Automatic cleanup follows the cleanupPeriodDays setting, which defaults to 30 days.^[1]

How are tools isolated per subagent?

By default, a subagent inherits every tool the main conversation has, including 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, and a tool listed in both is removed.^[1] 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. A handful of tools that depend on the main session's UI (such as AskUserQuestion, EnterPlanMode, and ExitPlanMode) are never available to subagents even when listed.^[1]

How do permissions work for a subagent?

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 and the classifier evaluates the subagent's tool calls with the same block and allow rules as the parent session. A child cannot escalate above the parent's permission posture.^[1]

Can a subagent spawn another subagent?

Yes, as of Claude Code v2.1.172, a subagent can spawn its own subagents, which is useful when a delegated task itself splits into parallel subtasks. Nesting is bounded by a fixed depth limit: a subagent at depth five does not receive the Agent tool and cannot spawn further, and the limit is not configurable. Only the top-level subagent's summary returns to the main conversation. To stop a specific subagent from spawning others, authors omit Agent from its tools list or add it to disallowedTools. Developers who need sustained, communicating workers instead use the agent teams feature, which gives each worker an independent context that can message its siblings.^[1]

How do you create a subagent?

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 details like the working directory, not the full Claude Code system prompt."^[1]

There are four authoring paths:

• Run /agents and pick Generate with Claude, which drafts the frontmatter and system prompt from a natural-language description (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. (Subagents are loaded at session start; files created through the /agents interface take effect immediately, but manual edits on disk require a restart.)^[1]
• Pass a --agents JSON blob when launching claude, which defines session-only subagents that are never saved to disk.

What goes in a subagent's frontmatter?

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

Scroll sideways for more →

Where are subagents stored, and which wins on a name clash?

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

Scroll sideways for more →

Project subagents are designed to be checked into version control; Anthropic recommends teams "check them into version control so your team can use and improve them collaboratively."^[1] 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]

What does the /agents command do?

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]

What are the 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]

Scroll sideways for more →

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: "This keeps exploration results out of your main conversation context."^[1] Explore returns a compact summary with file paths and short snippets. The Plan subagent plays a similar role inside plan mode. Both Explore and Plan skip CLAUDE.md files and the parent session's git status to keep research fast and inexpensive; every other built-in and custom subagent loads both.^[1] Users can disable any built-in subagent through the permissions.deny list in settings ("Agent(Explore)") or via the --disallowedTools "Agent(Explore)" flag.^[1]

How do you write a custom subagent?

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: "To encourage proactive delegation, include phrases like 'use proactively' in your subagent's description field."^[1] 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]

When should you use a subagent?

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. Anthropic's own decision rule says to use a subagent when "the task produces verbose output you don't need in your main context," when "you want to enforce specific tool restrictions or permissions," or when "the work is self-contained and can return a summary," and to stay in the main conversation for quick targeted changes or work that needs frequent back-and-forth.^[1]

Scroll sideways for more →

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. Anthropic warns directly: "Running many subagents that each return detailed results can consume significant context."^[1] 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 specific 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.

How do subagents compare 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, OpenAI Codex CLI, and Cline.

Scroll sideways for more →

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]

How do subagents relate to other Anthropic features?

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

Scroll sideways for more →

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 a fork as the right pick "when a named subagent would need too much background to be useful, or when you want to try several approaches in parallel from the same starting point."^[1] Because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's prompt cache, which makes forking cheaper than spawning a fresh subagent for the same context. Forks are gated behind the CLAUDE_CODE_FORK_SUBAGENT environment variable in earlier versions (the /fork command is enabled by default from v2.1.161) and a fork cannot spawn another fork.^[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]

How was the launch received?

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, nested subagents (v2.1.172), 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]

ELI5

Imagine you are doing a big project and you have one notebook. If you write down every little thing, the notebook fills up and you cannot find your main plan anymore. So you hand a small job to a helper who has their own notebook, lets them do all the messy scribbling, and they just tell you the answer at the end. Your notebook stays clean. A Claude Code subagent is that helper: it gets its own fresh space, its own instructions, and only the tools you decide to give it, then it reports back one short summary.

See also

• Anthropic
• Claude Code
• Claude Skills
• Claude (AI)
• Claude Agent SDK
• Model Context Protocol
• Cursor
• OpenAI Codex CLI
• Cline
• Context window
• System prompt
• Tool use (artificial intelligence)
• AI agent
• GitHub Copilot
• Plugin
• Slash command

References

1. "Create custom subagents." Claude Code Documentation. https://code.claude.com/docs/en/sub-agents (accessed June 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). ↩