Based on Anthropic’s official docs, checked November 5, 2026

Claude Code subagents: create, configure and run them

A subagent is a separate Claude Code worker with its own context window, system prompt and tool access. Claude hands it a task, it works through it, and only its result comes back to your main conversation, so long searches and noisy logs don’t fill your context. Claude Code ships with built-in subagents (Explore, Plan and general-purpose) and lets you define your own. This guide follows Anthropic’s subagents documentation, checked November 5, 2026.

1. 1. Create the agents folder

   Custom subagents are Markdown files with YAML frontmatter. Put project subagents in .claude/agents/ in your repository so your team gets them, or personal ones in ~/.claude/agents/ to use them in every project.

   mkdir -p .claude/agents

2. 2. Write the agent file

   name and description are the only required fields. The description is what Claude reads to decide when to delegate, so say exactly when to use it. The Markdown body becomes the subagent’s system prompt.

   ---
   name: test-runner
   description: Runs the test suite after code changes and reports failures with file and line.
   tools: Read, Grep, Glob, Bash
   model: sonnet
   ---
   Run the project tests, read the failures and report the smallest fix for each.

3. 3. Check the file

   Validate the frontmatter of your agent files before you rely on them.

   claude plugin validate .claude/agents

4. 4. Use it

   Claude delegates on its own when a task matches the description, or you can ask for the subagent by name in your prompt. Run /context to see which custom subagents loaded and where each came from.

Frontmatter fields you can set

Beyond name and description, optional fields include tools and disallowedTools (which tools it may use), model (sonnet, opus, haiku, fable or inherit), permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, isolation: worktree (its own git worktree), effort and color.

Limit tools to what the job needs. A read-only reviewer with Read, Grep and Glob can’t edit files even if its prompt goes wrong.

Where subagents load from

When two definitions share a name, Claude Code uses this order: managed settings first, then the --agents flag, then the project’s .claude/agents/, then your ~/.claude/agents/, then plugins. /doctor flags duplicate subagent names in the same directory.

Subagents that come from plugins ignore the hooks, mcpServers and permissionMode fields, for security.

Background subagents

From v2.1.302, subagents Claude spawns run in the background by default, so you can keep working while they run. Set CLAUDE_CODE_FORK_SUBAGENT=0 if you want Claude to wait for them instead. Press Ctrl+B to send running work to the background, and use /tasks to see what is running.

Background subagents get a reduced set of built-in tools, and their permission prompts appear in your main session.

Limits and usage

By default Claude Code runs up to 20 subagents at once (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) and lets them nest 3 levels deep (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Subagents count toward the same usage limits as your main conversation, so many parallel workers use your plan faster.

Each subagent’s transcript is saved under ~/.claude/projects/ in a subagents folder for that session.

Blocking a subagent

To stop Claude using a particular subagent, add a permission deny rule in the form Agent(name) to your settings.

Tips

• Write one subagent per job, with a description that names the trigger, such as “after code changes”.
• Give reviewers read-only tools and a separate worktree for anything that edits files in parallel.
• Commit .claude/agents/ so the whole team shares the same subagents.
• Watch your usage when you run many background subagents; they draw on the same plan limits.

Next steps

Sources

• https://code.claude.com/docs/en/sub-agents · checked 2026-11-05
• https://code.claude.com/docs/en/debug-your-config · checked 2026-11-05