Claude Subagents Explained: How They Work in Claude Code

Claude subagents let Claude Code hand off a task to a separate agent instance that runs in its own context window, with its own system prompt and its own tool access, then returns just a summary to the main conversation. Anthropic ships the feature directly in Claude Code and in the Claude Agent SDK, and a large open source ecosystem has grown up around ready-made subagent files.

Claude subagents are specialized AI assistants inside Claude Code that handle a task in an isolated context window and hand back only a final summary, so the main conversation never fills up with the search results, logs or file contents the subagent read along the way. Anthropic documents them for both Claude Code and the Claude Agent SDK.

How Claude subagents work

According to Anthropic's own Claude Code documentation, a subagent is a separate agent instance with four things that make it useful:

• Its own context window. A subagent starts fresh, does its work, and returns a summary. Files it read and tool calls it made do not accumulate in the parent conversation.
• A custom system prompt. The markdown body of a subagent file becomes its entire system prompt, not an addition to Claude Code's default one.
• Scoped tools. The tools frontmatter field is an allowlist (disallowedTools is the denylist), so a subagent built for review can be given Read, Grep, Glob and cannot edit files.
• Its own model. The model field routes a subagent to sonnet, opus, haiku, fable, a specific model ID, or inherit, which is Anthropic's documented cost lever: send routine work to a cheaper model and reserve the most capable one for hard reasoning.

Anthropic's Claude Code docs describe three ways to create one: programmatically through the agents parameter in SDK code, as a markdown file with YAML frontmatter in a .claude/agents/ directory, or by relying on the built-in general-purpose subagent that needs no configuration at all. The Agent SDK's own subagents page lists the same benefits in SDK terms: context isolation, parallelization (independent subtasks finish in the time of the slowest one instead of the sum of all of them), specialized instructions, and tool restrictions.

Subagent files can live in five places, in order of priority according to a widely read dev.to teardown of the feature: managed settings (organization-wide), the --agents CLI flag (current session), .claude/agents/ (checked into a project's git repo), ~/.claude/agents/ (every project for one user), and a plugin's own agents/ directory. Claude Code decides automatically which subagent fits an incoming task by matching it against each subagent's description field, or a user can invoke one explicitly by name.

Examples

A subagent file is markdown with YAML frontmatter. The example in Anthropic's Claude Code documentation for a code reviewer looks like this in shape:

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

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

The VoltAgent awesome-claude-code-subagents repository packages more than 161 ready-made subagents across ten categories, from typescript-pro and react-specialist to microservices-architect, installable individually as Claude Code plugins (claude plugin install voltagent-lang, for example). The repository has drawn 25,100 stars and 2,900 forks on GitHub.

A Hacker News commenter named CharlesW, replying to a thread on parallelizing development with subagents, described the pattern that keeps coming up in practice: he keeps a stytch.com/docs/llms.txt reference out of his main CLAUDE.md and instead loads it only into a dedicated auth subagent, so the main session's context stays clean while the auth subagent gets exactly the documentation it needs.

When to use it (and when not)

Anthropic's own guidance is to reach for a subagent when a side task would flood the main conversation with content nobody will reference again, or when the same kind of worker gets spawned repeatedly with the same instructions. It is not a persona layer: a dev.to writeup that built and tested 100 subagents across code review, debugging, security audits and incident triage put it plainly, calling a subagent "not a personality" but "a context firewall," and narrowed a 100-subagent collection down to twelve that were still in use, because overlapping description fields made Claude delegate to the wrong subagent, or none, and a large collection triggered less reliably than a small, sharp one.

The same skepticism shows up in the Hacker News discussion and in a year-old r/ClaudeAI thread asking what actually works: several practitioners argue persona-based subagents add "theatre" more than utility for coding tasks specifically, since the stack details already live in a project's CLAUDE.md and the model still calls the same file-read tools underneath. Where subagents demonstrably help, both threads agree, is isolating a specific chunk of documentation or a high-volume, low-value-per-token task like a big grep, not personality.

What's new (as of 17 September 2026)

Anthropic's weekly Claude Code digest documents several changes to subagents and adjacent multi-agent features through 2026:

• Week 27 (29 June to 3 July 2026): Claude Sonnet 5 became the default model for Pro, Team Standard and Enterprise seats, and subagents began running in the background by default, so Claude keeps working while a subagent runs instead of blocking on it.
• Week 30 (20 to 24 July 2026): Claude Opus 5 shipped as the new default Opus model, with a 1M-token context window and a fast mode priced at $10/$50 per million tokens, and /code-review began running as a background subagent.
• Week 32 (3 to 7 August 2026): Cross-session messaging shipped on macOS and Linux, letting separate Claude Code sessions (not subagents within one session) pass findings to each other directly.
• Week 33 (10 to 14 August 2026): Fork mode became the default in interactive sessions, letting Claude delegate a side task to a subagent that inherits the full parent conversation rather than starting fresh, which is a different tradeoff from the isolated-context default.
• Week 36 (31 August to 4 September 2026): Claude Fable 5.1 became available inside Claude Code with a 1M-token context window, and /skill-doctor shipped to show what each installed skill costs in context and how often it actually gets used.

Separately, Anthropic's agent-teams documentation describes an experimental, opt-in feature (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1) for coordinating multiple full Claude Code sessions as a team, with one session acting as lead and teammates working independently in their own context windows and messaging each other directly. As of v2.1.178, spawning a teammate needs no separate setup step; before that version, Claude used now-removed TeamCreate and TeamDelete tools to do it. Anthropic's own docs are explicit that agent teams are a heavier tool than subagents and recommend checking whether a subagent or cross-session messaging is enough before reaching for a team.

Key takeaways

• A Claude subagent is a separate agent instance with its own context window, system prompt, tool allowlist and model, defined as a markdown file with YAML frontmatter or programmatically via the Agent SDK.
• Subagents can live in five places with different scopes and priority, from organization-wide managed settings down to a single plugin's bundled agents.
• Since Anthropic's Week 27 2026 Claude Code release, subagents run in the background by default, and since Week 33, fork mode lets a subagent inherit the full parent conversation instead of starting empty.
• Practitioner write-ups on Hacker News, Reddit and dev.to converge on the same lesson: subagents earn their keep by isolating documentation or high-volume output, not by acting as named personalities, and a small curated set outperforms a large uncurated one.
• The VoltAgent awesome-claude-code-subagents collection packages more than 161 ready-made subagents across ten categories and has drawn over 25,000 GitHub stars.

FAQ

What is the difference between a Claude subagent and an agent team?

A subagent runs inside a single Claude Code session and returns a summary to that session's main conversation. An agent team, which Anthropic documents as experimental and off by default, coordinates multiple separate Claude Code sessions that each keep their own context and message each other directly, with one session acting as lead. Anthropic's own agent-teams documentation recommends trying subagents or cross-session messaging first, since teams add coordination overhead and use significantly more tokens.

Where do I put a custom Claude subagent file?

In a .claude/agents/ directory for a single project, checked into version control so a team shares it, or in ~/.claude/agents/ for a subagent you want available across every project on your machine. Anthropic's documentation also supports defining subagents through managed settings for an organization, through the --agents CLI flag for one session, or bundled inside a plugin's agents/ directory.

Do subagents actually help with coding tasks?

It is debated. A widely discussed Hacker News thread and a Reddit thread in r/ClaudeAI both surface practitioners who found large collections of persona-styled subagents added little beyond what a well-written CLAUDE.md already provides, while others reported real gains specifically from isolating a chunk of reference documentation, such as third-party API docs, inside a dedicated subagent instead of loading it into the main conversation. A dev.to teardown that tested 100 subagents kept only twelve, on the grounds that a subagent's real value is context isolation and tool restriction rather than persona.

Can I control which model a subagent uses?

Yes. The model field in a subagent's frontmatter accepts sonnet, opus, haiku, fable, a specific model ID, or inherit to match the parent session's model, which Anthropic's documentation describes as a direct cost lever for routing routine subagent work to a cheaper model.

Developers comparing ready-made subagent collections and other Claude Code tooling can browse them on the Claude Code listing on AI Agents Listing.