Claude Code subagents: how to create them, with examples and best practices

A Claude Code subagent is a helper Claude starts for a side task: it "runs in its own context window with a custom system prompt, specific tool access, and independent permissions," then returns only a summary, so your main conversation stays clean. Claude Code ships three you'll see most, Explore, Plan and general-purpose, and you can write your own as a Markdown file in .claude/agents/ with a name and a description. Since July 2026 subagents run in the background by default, up to 20 at a time, and they can start their own subagents up to three layers deep. Their requests count toward the same usage limits as your conversation.

Key takeaways

• What it is: a separate context window with its own prompt, tools and permissions, returning a summary (Anthropic).
• Make one: ask Claude to write it, or save a Markdown file with name and description in .claude/agents/ (project) or ~/.claude/agents/ (you).
• Model: inherits your conversation's model unless the file or CLAUDE_CODE_SUBAGENT_MODEL says otherwise.
• Runs: in the background by default, in parallel, up to 20 at once and three layers deep.
• Cost: no discount; a subagent's tokens come out of your plan or API bill like any other.

What is a subagent in Claude Code?

Anthropic's definition: "Subagents are specialized AI assistants that handle specific types of tasks." Use one "when a side task would flood your main conversation with search results, logs, or file contents you won't reference again" (Anthropic). The subagent does the reading in its own context and sends back what matters.

A subagent starts with a fresh context: it doesn't see your conversation, only the task Claude writes for it. The exception is a fork, started with /subtask, which inherits the whole conversation.

What are the built-in subagents?

• Explore: "A fast, read-only agent optimized for searching and analyzing codebases." It runs on your conversation's model and can't edit files. Claude asks it for a quick, medium or very thorough search.
• Plan: read-only research Claude uses in plan mode before presenting a plan.
• General-purpose: every tool, for multi-step work that both explores and changes code.
• Helpers: smaller agents Claude uses on its own, such as the one that sets up your status line.

Explore and Plan skip your CLAUDE.md files and the git status snapshot to stay fast. Earlier versions ran Explore on Haiku; it now inherits your model, so define your own Explore with model: haiku if you want it cheaper.

How do you create a subagent?

The quickest way is to ask: "Create a personal code-improver subagent in ~/.claude/agents/ that... make it read-only and have it use Sonnet." Claude writes the file. Or write it yourself:

---
name: code-reviewer
description: Expert code review specialist. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior reviewer. Check for bugs, security problems and
missing tests. List findings by severity with file and line.

Where the file lives decides who gets it. When two share a name, the higher one wins (Anthropic):

1. Managed settings, set by an organization.
2. The --agents flag, JSON for one session.
3. .claude/agents/ in the project, which you commit for your team.
4. ~/.claude/agents/ for every project on your machine.
5. A plugin's agents/ folder (Claude Code plugins).

Since v2.1.198 (July 2026), /agents no longer opens a wizard; it reminds you to ask Claude or edit those folders. If a new subagent doesn't show up, restart Claude Code: a running session doesn't notice a newly created agents folder.

What can you put in a subagent's frontmatter?

Only name and description are required. The optional fields (Anthropic):

• tools and disallowedTools: which tools it may use, or may not.
• model: sonnet, opus, haiku, fable, a full model ID, or inherit.
• permissionMode: its own permission mode.
• maxTurns and effort: how long and how hard it works.
• skills and mcpServers: skills and MCP servers to load.
• hooks: hooks that run only for this subagent (Claude Code hooks).
• memory: a folder of notes it keeps between sessions.
• background: always run in the background.
• isolation: worktree: work in its own git worktree.
• omitClaudeMd: start without your CLAUDE.md files.
• initialPrompt, color and experimental: a first prompt when it runs as the main agent, a display color, and options such as a one-hour prompt cache.

Everything below the frontmatter is the subagent's system prompt.

Which model does a subagent use?

In order: the model Claude passes when it starts the subagent, the file's model field, the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then your conversation's model. inherit means "use the same model as the main conversation." Since v2.1.251 (August 2026) the environment variable is only a default; set CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 as well to put every subagent on one model. The variable alone doesn't move Explore or Plan. Run /tasks to see which model each subagent is using.

A cheaper model for routine subagents is one of Anthropic's tips for reducing token usage.

How do you use a subagent?

• Let Claude choose: it delegates based on the task and each subagent's description. Phrases like "use proactively" in the description encourage it.
• Ask by name: "Use the test-runner subagent to fix failing tests."
• @-mention it: @agent-code-reviewer "guarantees the subagent runs" for one task.
• Make it the whole session: claude --agent code-reviewer runs your main thread with that agent's prompt, tools and model.

Subagents run in the background by default in an interactive session, so you can keep working; a permission prompt from one appears in your main session with its name. Claude can start several at once for independent searches, and you can type into a running subagent's transcript to steer it.

How many subagents can run at once, and how deep?

• At once: 20 by default; the 21st fails with "Concurrent subagent limit reached." CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes it.
• Nesting: a subagent can start its own, "up to three layers below the main conversation." CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 turns nesting off.

Subagent memory and worktrees

The memory field gives a subagent a notes folder that survives between sessions: user (yours, every project), project (.claude/agent-memory/<name>/, shareable in git) or local (the project, not committed). Anthropic recommends project. It loads the first 200 lines of the folder's MEMORY.md, as Claude Code's memory does.

isolation: worktree runs the subagent in its own git worktree, removed afterwards if it changed nothing, so parallel subagents don't edit the same files (Claude Code worktrees). Hooks can watch them through the SubagentStart and SubagentStop events.

Subagent examples

Anthropic's docs include four you can copy (Anthropic):

• Code reviewer: "Expert code review specialist. Proactively reviews code for quality, security, and maintainability." Read-only tools.
• Debugger: "Debugging specialist for errors, test failures, and unexpected behavior."
• Data scientist: "Data analysis expert for SQL queries, BigQuery operations, and data insights."
• Database query validator: runs read-only database queries, with a hook that blocks writes.

Subagent best practices

Anthropic's four (Anthropic):

1. "Design focused subagents": each should excel at one task.
2. Write descriptions that single out one subagent, because the description is how Claude picks it. All descriptions together share a 15,000-token budget.
3. "Limit tool access": a reviewer doesn't need Edit or Write.
4. "Check into version control," so the team shares project subagents.

Its general guide adds: when Claude has to read a lot to answer a question, "use subagents to investigate" so the file contents never fill your main context (Claude Code best practices).

Subagents vs skills vs agent teams

• Subagent: a separate context that does a task and returns a summary. Use it for noisy reading, searching and checks.
• Skill: instructions loaded into your main conversation when relevant; it "adds to your main window" (Claude Code skills).
• Agent team: several full Claude Code sessions with a lead, a shared task list and messages between teammates. Experimental and off by default, and Anthropic puts it at about 7x the tokens in plan mode (agent teams).

A skill can also run in a subagent (context: fork), and a subagent can preload skills (skills).

Do Codex and Cursor have subagents?

Yes. Codex enables subagents by default, with built-in default, worker and explorer agents and custom ones as TOML files in .codex/agents/ (OpenAI). Cursor has Explore, Bash and Browser subagents, and also reads .claude/agents/ (Cursor).

How have subagents changed?

• July 24, 2025 (v1.0.60): custom subagents and /agents launched.
• October 2025: the Explore and Plan subagents arrived.
• December 2025: subagents could run in the background.
• February 2026: agent teams (experimental), subagent memory and worktree isolation.
• June to July 2026: nesting, then background by default, the /agents wizard removed, a limit of 20 at once, and nesting three layers deep.
• August 2026 (v2.1.251): CLAUDE_CODE_SUBAGENT_MODEL became a default rather than an override.

From Anthropic's changelog (GitHub).

Subagents for a whole team

A committed .claude/agents/ folder gives every teammate the same reviewers and helpers, but each person still runs them in their own session. In Poly (usepoly.co), a team works with one Claude Code or Codex agent in a shared browser room, using the repository's agents and CLAUDE.md; everyone sees each step live, and any member can approve a change before it happens. Free to start. What is Poly?