Claude Code subagents

Who this is for and what you will be able to do

This guide is for people whose main conversation is being filled with search results, logs or file contents, or who want a reviewer that can read but not edit. By the end you should be able to write a subagent file, restrict its tools, choose the right directory for it, and invoke it in one of three ways ^[1].

What a subagent is and when to use one

A subagent is a specialized assistant for a particular kind of task. It has its own context window, a custom system prompt, its own tool access and independent permissions. Use one when a side task would fill the main conversation with search results, logs or file contents you will not refer to again. The subagent does that work in its own context and returns the result ^[1].

The docs list five benefits: keeping exploration out of the main conversation, limiting its tools, reusing user-level subagents across projects, focusing its behavior with a system prompt, and controlling cost by routing work to faster, lower-cost models such as Haiku. Its own requests count toward the same usage limits as the main conversation ^[1].

Write a subagent file

A subagent is a Markdown file with YAML frontmatter. Only name and description are required, and the body is the system prompt. The docs' example is a code reviewer:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

A subagent receives only its own system prompt and basic environment details, such as the working directory ^[1]. The description tells Claude when to delegate, so make it clear. Descriptions take up context, and when the combined descriptions of non-built-in subagents exceed 15,000 tokens, Claude Code shows a warning at startup ^[1].

Useful frontmatter fields include tools, disallowedTools, model (sonnet, opus, haiku, fable, a full model ID or inherit), permissionMode, maxTurns, skills, mcpServers, hooks, memory, effort, and isolation, which set to worktree runs the subagent in a temporary git worktree ^[1]. Field names are camelCase and must match exactly. Claude Code ignores a field it does not recognize without reporting an error. To find a misspelled field, run claude --debug and search the debug log for does not recognize or apply ^[1].

Where to store it

Storage location sets the scope. From highest to lowest priority: organization-wide managed settings, the --agents CLI flag for the current session, .claude/agents/ for the current project, ~/.claude/agents/ for all your projects, and a plugin's agents/ directory. When names collide, the higher-priority one is used ^[1].

Project subagents are meant to be checked into version control so the team can share and improve them. Subagents passed with --agents as JSON exist only for that session and are not saved to disk, which suits quick tests and scripts ^[1].

Claude Code watches the agent directories, and a change is picked up within a few seconds. If you create the first agent file in a directory that did not exist when the session started, restart Claude Code to load it ^[1].

Some files are skipped without an error in the session: those without a name, with a name that starts with -, contains : or is longer than 256 characters, with a name but no description, or with YAML that does not parse. The docs suggest claude plugin validate to check a directory ^[1].

Limit what it can do

tools is an allowlist and disallowedTools is a denylist. If both are set, the denylist is applied first and the allowlist is resolved against what remains ^[1]. The docs' example allows only Read, Grep, Glob and Bash, so the subagent cannot edit or write files and cannot use any MCP tools ^[1].

permissionMode accepts default (manual, which prompts), acceptEdits, auto, dontAsk, bypassPermissions and plan, and manual is an alias for default. If the main conversation is already in bypassPermissions, acceptEdits or auto mode, the subagent runs in that mode and its own setting is ignored ^[1].

maxTurns caps the number of turns. When the cap is reached, the output is marked partial, and Claude can resume the subagent to continue ^[1]. The skills field loads the full content of the listed skills into the subagent's context at startup ^[1].

Plugin subagents do not support the hooks, mcpServers or permissionMode fields, which are ignored when they load from a plugin ^[1].

How to invoke it

There are three ways. You can name it in your prompt, for example "Use the test-runner subagent to fix failing tests", and Claude usually delegates. You can @-mention it, as in @"code-reviewer (agent)" look at the auth changes, which guarantees that subagent runs for the task. Or you can run the whole session as that subagent with claude --agent code-reviewer ^[1].

To make a subagent the project default, set "agent": "code-reviewer" in .claude/settings.json. The --agent flag overrides this setting when both are present ^[1].

Foreground and background

A foreground subagent blocks the main conversation until it finishes, and its permission prompts come to you directly. A background subagent runs alongside your work. When it needs permission, Claude Code shows the prompt in the main session and names the subagent asking ^[1].

A common use is keeping verbose test output out of the main conversation: "Use a subagent to run the test suite and report only the failing tests with their error messages." The main conversation then gets only the failures and their messages ^[1].

Concurrency limit and forks

By default, 20 subagents can run at once in a session. Spawning another with the Agent tool then fails with Concurrent subagent limit reached, and the error tells Claude not to retry ^[1].

A fork is a subagent that inherits the whole conversation so far. Only its final result returns to the parent conversation. Start one with /subtask followed by a task, such as "draft unit tests for the parser changes so far" ^[1].

Next steps

Start with a read-only reviewer, see how it behaves outside the main conversation, and then decide whether to add more. The full field list and examples are in the official subagent documentation ^[1].