Claude Code Subagents: A 2026 Practical Guide

You're three hours into a refactor. The main Claude Code session has read 40 files, summarized two ADRs, and is now drafting a migration script. You ask it to "also check whether any of these touch the auth pipeline," and watch the context window balloon past 70%. Two prompts later, it's auto-compacting, and you've lost the thread.

This is the problem subagents fix. Instead of pouring every research detour into the same conversation, you delegate the side quest to a child instance with its own context window, tools, and model. The parent session stays focused on the work that pays the bills.

What Are Claude Code Subagents?

Claude Code subagents are specialized Claude instances that handle specific types of tasks. Each runs in its own context window with a custom system prompt, a scoped tool list, and independent permissions. The parent session delegates work to the subagent, the subagent does the work in isolation, and the parent gets back only the summary. You define each subagent as one of the markdown files in .claude/agents/, with YAML frontmatter at the top; the body becomes the system prompt that guides its behavior.

Everything else (naming, scope, tool restrictions, model choice, hooks, and memory) sits on top of that base.

Why Subagents Matter: Context Isolation

Think of the parent session as the project lead and the subagent as a contractor brought in for one narrow job. A long-running Claude Code session accumulates everything: file reads, tool outputs, intermediate reasoning, and dead ends. Each token in that history costs money on the next turn and crowds out room for the next file you actually need. Auto-compaction kicks in around 95% capacity, which is fine as a safety net but is lossy in practice.

Subagents flip the script. The parent agent decides what work needs doing, hands a tightly scoped task to a child, and the child operates on its own canvas. When it's done, only the result returns to the parent, while the 4,000-line stack trace, the 15 grep results, and the false leads all stay in the subagent's transcript and never pollute the parent run.

There's a second-order benefit. Because the subagent can run with a much narrower task prompt and toolset, you can usually give it fewer instructions than the parent session requires. A code reviewer agent doesn't need the whole kitchen sink in the preamble; it needs a short review brief, a read-only toolset, and a clear output format. That produces more reliable behavior on the specialized task.

The tradeoff: each subagent invocation creates a fresh instance with no memory of prior runs unless you explicitly enable persistent memory or resume the session. For one-shot research, that's the feature. For ongoing context, you'll need to design around it.

Built-in Subagent Types

You don't have to write Markdown files to start. Claude Code ships built-ins, including Explore, Plan, and general-purpose. Each targets a different mode of work:

• Explore: a fast, read-only agent optimized for searching and analyzing codebases. It runs on Haiku and is denied access to Write and Edit tools, so it can't accidentally mutate your repo. Most parents pass it a "thoroughness level" of quick, medium, or very thorough.
• Plan: read-only, used during plan mode to gather codebase context without infinite nesting. Inherits the parent's model.
• General-purpose: the catch-all. Inherits all tools, used for complex multi-step research and code modifications outside plan mode when no specialist fits.

If your work fits one of the built-ins, use it. The custom subagents below are for when it doesn't.

How to Create a Custom Subagent

Here's the workflow, in order:

1. Run /agents inside Claude Code to open the management interface.
2. Pick a scope: project (.claude/agents/) or user (~/.claude/agents/).
3. Write the Markdown file with YAML frontmatter on top and the system prompt below.
4. Choose a model that fits the task (Haiku, Sonnet, or Opus).
5. Restrict the tool list to only what the subagent needs.

Each step has a wrinkle worth covering.

Use the /agents command

The /agents command opens a tabbed interface for managing subagents. The Library tab lists every built-in, user, project, and plugin subagent; the Running tab shows live subagents you can stop or open. You create new subagents with guided setup, edit agent definitions, or delete custom ones. Anthropic recommends this as the default way to manage subagent agent definitions.

# In an active Claude Code session  
/agents

# Or list configured subagents from the shell  
claude agents  

Choose the subagent scope (project vs. user)

Most teams only need two scopes: project agents in .claude/agents/ when the agent belongs to the repo, and user agents in ~/.claude/agents/ when it should follow a developer across repos. The full precedence order from highest to lowest is: managed settings, the --agents CLI flag, .claude/agents/ (project), ~/.claude/agents/ (user, across all your projects), then any plugin's agents/ directory. When two subagents share a name, the higher-priority one wins.

• Project scope for anything coupled to the codebase: a code reviewer that knows your conventions, a test writer that targets your framework. Check it into git. Pair it with CLAUDE.md best practices so the subagent inherits the project's working agreements.
• User scope for personal helpers that travel with you: a "summarize this PR" helper that's the same everywhere.

Write the subagent markdown file (frontmatter + system prompt)

Here's a minimal code-reviewer definition that's safe to drop into .claude/agents/code-reviewer.md:

---  
name: code-reviewer  
description: Use proactively after a feature branch is staged to review for quality, security, and best practices.  
tools: Read, Glob, Grep  
model: sonnet  
---  
You are a senior code reviewer. When invoked, do the following in order:

1. Identify the files changed on the current branch.  
2. Read each changed file and its tests.  
3. Flag specific issues by file and line: correctness, security, performance, readability.  
4. Suggest concrete fixes, not vague advice.

Output format: a Markdown report grouped by file, with severity tags (BLOCKER, MAJOR, NIT).  
Do not modify files; you are read-only by design.  

Only the name and description fields are required. Everything else is optional and inherits sensible defaults. The body of the file becomes the system prompt, so write it like a job description, not a conversation.

A few tips for reliable automatic delegation:

• Start the description with "Use this agent when..." or include "use proactively" so the parent recognizes when to hand off.
• State the output format explicitly. The parent receives the subagent's result, so the output shape matters.
• Keep the system prompt short. Subagents work best with one job and a clear definition of done.

Pick a model (Haiku/Sonnet/Opus tradeoffs)

The model field accepts sonnet, opus, haiku, a full model ID like claude-opus-4-7, or inherit, and defaults to inherit. Picking the right one is where most cost optimization happens.

In production, CLAUDE_CODE_SUBAGENT_MODEL takes the highest precedence and forces every subagent in a session to use one model. Useful for cost ceilings or compliance.

Restrict tool access (Read, Grep, Glob, Bash, etc.)

Two frontmatter fields control tool access. The tools field is an allowlist; specify it, and the subagent can only use those tools, omit it, and it inherits all tools. The disallowedTools field is a denylist subtracted from whatever the subagent would otherwise have. If both are set, disallowedTools is applied first, then tools is resolved against the remaining pool.

Some patterns that work:

• Read-only auditors get the Read Grep Glob toolset (Read, Grep, Glob).
• Bug-fixing subagents need Read, Edit, Bash so they can run tests and apply patches.
• Doc subagents add WebFetch and WebSearch for citations.
• Database query validators that need Bash get a PreToolUse hook that blocks INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE. The tools field can't express "read-only SQL"; hooks can.

The Agent tool (renamed from Task in v2.1.63; old aliases still work) is how a parent spawns subagents. The Agent tool is rarely needed inside the subagent itself, but subagents themselves can't spawn other subagents. You'll rarely allowlist the Agent tool inside a subagent's tools.

Invoking Subagents: Automatic vs. Explicit Delegation

There are four ways to actually run a subagent. Pick whichever matches the precision you need.

Automatic delegation. The parent decides. Claude routes based on the task description in your prompt, the description field on each subagent, and the current context. Good descriptions make this magical. Bad ones make it frustrating.

Natural language by name. "Use the test-runner subagent to fix the failing tests in auth/." Claude almost always honors this, but it's still a hint, not a guarantee.

@-mention. Type @ in the prompt and pick from the typeahead, or write @agent-<name> directly. This guarantees the subagent runs for one task. Plugin subagents show up as <plugin-name>:<agent-name>.

Session-wide via --agent. Run claude --agent code-reviewer and the entire main thread becomes that subagent: its system prompt, its tool list, its model. Useful for "this whole CI run is a security review."

Foreground vs. background is the other axis. Foreground subagents block the main conversation until they finish; permission prompts pass through to you. Background subagents run concurrently. Before launching, Claude Code prompts for any tool permissions the background subagent will need; once running, it inherits those permissions and auto-denies anything not pre-approved. Press Ctrl+B to background a running task. If you need to disable backgrounding entirely (CI environments, locked-down workstations), set CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1.

For real parallelism, fork mode is the option. Forks are experimental and require Claude Code v2.1.117 or later, enabled by setting CLAUDE_CODE_FORK_SUBAGENT=1. A fork inherits the entire conversation so far instead of starting fresh, which means its first request reuses the parent's prompt cache and is cheaper than spawning a brand-new subagent. The catch: a fork can't spawn further forks, so you can't build deep trees this way. For more on dispatching work in parallel, see our walkthrough on running Claude Code in parallel.

Production-Ready Subagent Patterns

After a few weeks of running subagents in real codebases, the same handful of definitions show up everywhere. Here's a starter set, drawn from the VoltAgent awesome-claude-code-subagents repo (100+ subagents and counting) and the official Anthropic Claude Code docs.

A note on each:

• code-reviewer stays read-only on purpose. Sonnet hits the right cost/quality balance; for security-critical code, swap to Opus.
• debugger keeps Edit and Bash so it can iterate: reproduce, patch, retest. Without Bash it can theorize but never confirm.
• security-auditor runs on Opus and gets only Read, Grep, Glob. Subtle pattern recognition is where Opus pulls away from Sonnet, and a Read Grep Glob toolset is enough.
• doc-maintainer runs on Haiku because it's mostly file ops. WebFetch/WebSearch lets it pull canonical examples for tricky API references.

For more habits that teams have seen work, Claude Code productivity tips collect what pays off across teams.

Subagents vs. Skills vs. Agent Teams

These three concepts are constantly conflated on Reddit and in PR reviews. Here's the clean version.

Anthropic's one-line distinction: subagents work within a single session, while agent teams coordinate across separate sessions. Skills are the third axis. They extend what Claude can do via a SKILL.md file with YAML frontmatter and Markdown content; the body loads only when invoked. Use skills when you want a reusable prompt that runs in the main conversation context rather than an isolated subagent context.

Agent teams require Claude Code v2.1.32 or later and are enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Each teammate gets their own context window and is fully independent. Token cost is higher because every teammate is a separate Claude instance, but you get true peer-to-peer coordination.

Rule of thumb: reach for subagents first. Move to skills when you want the same instructions in line. Move to agent teams when one specialist isn't enough, and they actually need to talk through a plan.

Subagents in Team Workflows

Subagents solve in-session context isolation beautifully. They don't solve the problem that the session itself is tied to your laptop.

That's a real cost on a team. Half the value of a coding agent is being able to throw a ticket at it and walk away. If your workflow depends on a local terminal session, you still have local-machine friction: permissions, environment setup, one checkout, and one developer's machine. Multi-repo work is worse: a single feature might touch the API repo, two client SDKs, and an infra repo. Even a subagent-rich Claude Code session is single-machine, single-checkout.

Background coding agents fill that gap; see our overview of background coding agents. The pattern: a Linear ticket, Slack mention, or webhook fires; an isolated cloud sandbox spins up; Claude Code runs inside it with your custom subagents and your CLAUDE.md; PRs come back for review. You stay in your editor instead of in front of a terminal.

Tembo is the platform we built for this layer. It runs Claude Code (and Codex, Cursor, and other agents) on off-developer machines in sandboxed VMs with the right runtimes preinstalled. Tag @tembo on a Linear ticket; it picks up the work, runs your subagents in the cloud, and opens a PR. A single task can open coordinated PRs across multiple repositories, even across platforms, which matters when an API change has to land in client libraries the same day. Self-hosted in your VPC if you can't ship code outside your network. Tembo isn't a Claude Code alternative; it's the runtime that lets you treat Claude Code as a service your team can dispatch work to.

For the broader pattern, see our pieces on coordinating multi-agent workflows and async coding agents. Subagents make a single session smarter; background runners make a team faster.

Limitations and Pitfalls

Subagents are powerful, but they're not free. Things to watch:

• No nested subagents. Subagents cannot spawn other subagents. If you need deep delegation, chain them from the main conversation or use skills.
• Latency hit. Subagents start fresh and need time to gather context. For quick targeted edits, the main conversation is faster.
• bypassPermissions is dangerous. It skips all permission prompts, including writes to .git, .claude, .vscode, .idea, and .husky. Reach for it only in throwaway environments.
• Background subagents auto-deny new tools. If a background subagent hits an unapproved tool, that call fails, but the subagent keeps going. Re-run as a foreground subagent.
• Plugin subagents drop hooks, mcpServers, and permissionMode. If you need any of those, copy the file into .claude/agents/ and own it.
• cd doesn't persist inside a subagent. Switching directories in one Bash call doesn't carry to the next. Use isolation: worktree for real working-directory isolation.
• Each invocation is a fresh instance. Memory is opt-in via the memory frontmatter field.
• Confirmation overhead at scale. Many subagents returning detailed results still consume context in the parent. Aggressively summarize in the system prompt.

The summary: subagents are a great context-isolation primitive, not a magic productivity wand. They reward careful design and punish "I'll just spawn ten of these and see what happens."

Wrapping Up

Subagents are one of the simplest ways to make long Claude Code sessions more reliable. Define a few specialists, scope their tools tightly, and write descriptions that trigger automatic delegation so the parent session doesn't drown in detail. Start with one specialist (a code-reviewer subagent is the safest first move), measure how often it is invoked, and add more as patterns emerge.

When you've outgrown the single-machine model, the next step is moving the runtime off your laptop. Try Tembo free and run your agents and subagents in the cloud against Linear tickets and Slack threads while you sleep.

FAQ

How do I use Claude Code sub agents? Run /agents in an active Claude Code session, create or pick a subagent, and either let Claude delegate to it automatically based on its description or invoke it explicitly with an @-mention or by name. For session-wide use, run claude --agent <name>.

What are subagents in Claude Code? Specialized Claude instances with their own context window, system prompt, and tool list. The parent delegates work and gets back only a summary, so its context stays clean.

How do I create a subagent in Claude Code? Use the /agents interface (recommended) or drop one of your agent files (a Markdown file with YAML frontmatter) into .claude/agents/ (project) or ~/.claude/agents/ (user). Required fields are name and description.

Subagents vs. skills, what's the difference? Subagents run in an isolated child context and return a summary; skills run in the main conversation and load on demand. Use a skill when you want the instructions inline; use a subagent when you want the noisy intermediate work to stay out of the parent transcript.

Can I run Claude Code subagents in parallel? Yes. Background subagents run concurrently with the main conversation (Ctrl+B), and fork mode (CLAUDE_CODE_FORK_SUBAGENT=1, v2.1.117+) lets you spawn forks that share the parent's prompt cache. For multi-repo or multi-machine parallelism, you'll want a background runner outside Claude Code itself.

Do subagents inherit the parent's tools and skills? They inherit tools by default, and you can restrict them with tools or disallowedTools. They do not inherit skills; declare them explicitly in the skills frontmatter field if you want them.