Claude Code subagents: when and how to use them

What is a Claude Code subagent?

A Claude Code subagent is a specialized assistant that handles one kind of side task in its own context window, with its own system prompt, tool access and permissions, and returns only a summary to your main conversation. Anthropic’s subagent docs say to use one when a side task would flood your conversation with search results, logs or file contents you will not reference again. Define a custom one when you keep spawning the same kind of worker.

Two costs come with that. Each subagent sends its own requests, which count toward the same usage limits as your main conversation. And a subagent starts fresh: it does not see your conversation history, only the task message Claude writes for it, its own system prompt and, for custom subagents, your CLAUDE.md files and git status, per what loads at startup. The built-in Explore and Plan agents skip those two, so if a rule must reach one of them, such as “ignore the vendor/ directory,” restate it in your prompt.

When should you use a subagent?

Use one when the task produces verbose output you do not need in your main context, when you want to enforce specific tool restrictions, or when the work is self-contained and can return a summary. Stay in the main conversation when the task needs frequent back-and-forth, when planning, implementation and testing share a lot of context, when the change is quick, or when latency matters, because a fresh subagent has to gather context first. That split comes from the docs’ choose between subagents and the main conversation.

The docs name three patterns that work. Isolate high-volume operations, such as “Use a subagent to run the test suite and report only the failing tests with their error messages.” Run parallel research, with separate subagents on the authentication, database and API modules. Chain subagents, so one finds problems and the next fixes them. See common patterns.

A subagent is also a fresh pair of eyes. Anthropic’s best practices suggest having a subagent review the diff in a fresh context, because it sees only the diff and your criteria, not the reasoning that produced the change. For a question about something already in your conversation, use /btw instead.

What does a subagent definition look like?

A subagent is a Markdown file with YAML frontmatter, and the body is its system prompt. Project subagents live in .claude/agents/ and can be checked into version control. Personal ones live in ~/.claude/agents/. Only name and description are required, and Claude uses the description to decide when to delegate, so make it specific. The scope table also covers the --agents flag, managed settings and plugins.

The fields you will use most are tools (an allowlist), disallowedTools (a denylist), model, maxTurns, skills to preload skills, isolation: worktree for a temporary git worktree, and permissionMode. A misspelled field is ignored without an error, and the frontmatter reference lists them all. /agents no longer opens a wizard: after v2.1.197 it prints a reminder to ask Claude to write the file, or to edit the folders yourself.

What are three example subagents?

Save each one as a Markdown file in .claude/agents/, with the fields between two --- lines and the prompt below them.

Test runner. name: test-runner, description: Runs the test suite and reports only the failing tests with their error messages. Use after code changes., tools: Bash, Read, Grep and model: haiku. The prompt says to run the project’s test command and reply with the failing test names, the first error line of each and the file it points to, nothing more. It keeps pages of passing output out of your context, and Anthropic’s cost docs suggest model: haiku for simple subagent tasks.

Reviewer. name: code-reviewer, description: Reviews the current diff for bugs, missing tests and risky changes. Use after code changes., tools: Read, Grep, Glob, Bash and model: inherit. The prompt says to run git diff, read the changed files and list problems in order of risk, with file and line, without editing anything. It has no Edit or Write tool, though Bash can still run commands that change files, so deny the ones you care about in permissions.deny. Anthropic’s docs have a fuller code reviewer.

Directory refactorer. name: refactorer, description: Applies one mechanical change to one directory and runs that directory’s tests. Use once per directory in a larger migration., tools: Read, Edit, Grep, Glob, Bash, model: sonnet, isolation: worktree and maxTurns: 30. With isolation: worktree it works in a temporary git worktree. By default that branches from the repository’s default branch on the remote, not your current HEAD, unless worktree.baseRef is set to "head", per the worktree docs. Claude Code removes the worktree if the subagent changes nothing. At maxTurns it stops and returns partial output that Claude can resume. For big migrations the built-in /batch command does this at scale: it splits the work into 5 to 30 units, each handled by a background subagent in its own worktree, per the command reference.

How do you choose a subagent’s model?

As of October 2026, model takes sonnet, opus, haiku, fable, a full model ID or inherit. Claude Code resolves the model in this order: the model Claude passes for that call, the model field in the definition, the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then your main conversation’s model. See choose a model.

Match the model to the job. Anthropic’s cost docs say Sonnet handles most coding tasks well and costs less than Opus, and to save Opus for complex architectural decisions or multi-step reasoning. A subagent’s context window is sized by its own model, so delegating to a model with a smaller window gives that subagent the smaller window. To check which model a running subagent uses, run /tasks. To put every subagent on one model, set CLAUDE_CODE_SUBAGENT_MODEL together with CLAUDE_CODE_SUBAGENT_MODEL_FORCE set to 1. Both points are in the model section of the docs.

Subagents vs skills vs agent teams: which one do you need?

Skills and subagents solve different problems. Skills are reusable content you can load into any context. Subagents are isolated workers that run separately from your main conversation, per Anthropic’s comparison. A skill adds to your main context window, while a subagent uses a separate one and returns a summary. They combine in both directions: a subagent can preload skills with the skills field, and a skill can run in an isolated subagent with context: fork, as the skills docs explain.

Agent teams are a heavier tool. Subagents report results back to the main agent. In an agent team, teammates share a task list, claim work and message each other directly. Anthropic says to use subagents for quick, focused workers that report back, and agent teams when teammates need to share findings and challenge each other. Teams are experimental and off by default, and the cost docs say they use about 7 times more tokens than a standard session when teammates run in plan mode. See the agent teams docs.

One neighbor is worth knowing. A fork, started with /subtask, is a subagent that inherits your whole conversation. It suits tasks where a fresh subagent would need too much background, and it costs less than a fresh one for those tasks because it shares your prompt cache. See fork the current conversation.

What are the best practices for subagents?

One job each. Anthropic’s advice is to design focused subagents that each excel at one task, and to write descriptions specific enough to route to the right one. Add a phrase like “use proactively” if you want delegation without being asked, and keep descriptions short: past 15,000 tokens combined, Claude Code warns at startup.

Least privilege. Grant only the tools the job needs, with tools or disallowedTools, and check project subagents into version control so your team can improve them, as the same docs advise.

Cap the cost. Pick a cheaper model for simple work and set maxTurns. Nesting is on by default, up to three layers below your main conversation. Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to 1 to turn it off, per nested subagents.

Be explicit when it matters. Name the subagent in your prompt, @-mention it to guarantee it runs for one task, or start a whole session as that subagent with claude --agent code-reviewer. See invoke subagents explicitly.

Expect background runs. In interactive sessions, subagents Claude spawns run in the background by default, and a background subagent that needs permission surfaces the prompt in your main session, per foreground and background. Our guides to running several Claude Code sessions and multi-agent workflows with approvals cover the wider picture.

Run Claude Code with the rest of your agents

Subagents live inside one Claude Code session, and SwarmPane does not replace them. Code mode runs Claude Code in a real terminal, so you define and use them the way you do in any terminal. What SwarmPane adds is the view around that session. Agent Grid runs up to 16 agents in real terminals, each pane showing whether it is working, waiting for you or done. Status comes from each CLI’s own signals, such as Claude Code hooks. SwarmPane also has its own Skills: reusable instructions that are included whenever you assign the skill to a teammate.

SwarmPane runs the agent CLIs and accounts you already have, so Anthropic bills its plan separately. Start with a 7-day trial for $1 and cancel before it ends if it is not for you.