Claude Code Subagents: How to Create and Use Them (2026)

Claude Code subagents are “specialized AI assistants that handle specific types of tasks”. Each runs in its own context window with its own system prompt, tool access and permissions, and returns only its final result to your main conversation. Claude delegates to them automatically based on each one’s description, or you can name one. Custom subagents are Markdown files in .claude/agents/.

Key points

What they are Helpers with their own context window, system prompt, tools and permissions
Built in Explore (read-only search), Plan (read-only research for plan mode), general-purpose
Custom ones Markdown files with YAML frontmatter in .claude/agents/ (project) or ~/.claude/agents/ (you)
Required fields name and description
When they run Claude delegates using each description, or you name the subagent
Parallel Subagents Claude spawns start in the background; up to 20 run at once by default
Context A subagent doesn’t see your conversation history; only its result comes back

The built-in subagents

  • Explore: “a fast, read-only agent optimized for searching and analyzing codebases.” It can’t write or edit files.
  • Plan: “a research agent used during plan mode to gather context before presenting a plan.” Read-only.
  • general-purpose: “a capable agent for complex, multi-step tasks that require both exploration and action,” with every tool subagents can use.

Create your own

Ask Claude to write one, or create the file yourself. A reviewer that can only read code:

---
name: code-reviewer
description: Reviews a diff for correctness bugs. Use after code changes.
tools: Read, Grep, Glob
model: sonnet
---

You review code changes for correctness bugs. Report each finding with the file, the line
and a failure scenario. Don't edit files.

Save it as .claude/agents/code-reviewer.md to share it with your team through the repo, or in ~/.claude/agents/ to keep it to yourself. tools limits what it can use (omit it to inherit every tool), and model picks sonnet, opus, haiku, fable, a full model ID or inherit. Other fields include permissionMode, maxTurns, mcpServers, memory and isolation: worktree.

How Claude decides to use one

“Claude uses each subagent’s description to decide when to delegate tasks,” so write the description as a trigger: what it does and when to use it. You can also ask for one by name in your prompt.

Parallel work and limits

  • Subagents that Claude spawns start in the background and run at the same time; the default limit is 20 at once (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS).
  • A subagent doesn’t see your conversation history, and only its final result returns to the main conversation, which keeps noisy output out of your context.
  • Subagent requests count toward the same usage limits as your main conversation.

Subagents vs agent teams

Subagents Agent teams
What Helpers inside your session A lead session that spawns and supervises teammate sessions
Status Available Experimental, off by default
Who it serves One person One person

Neither connects two people’s agents. For that, see Claude Code multiplayer and Claude Code for teams.

Frequently Asked Questions

What are subagents in Claude Code?

Specialized assistants that each run in their own context window, with their own system prompt, tools and permissions. Claude hands them part of a task and gets back only the result.

How do I create a Claude Code subagent?

Ask Claude to write one, or add a Markdown file with name and description in its YAML frontmatter to .claude/agents/ (shared through the repo) or ~/.claude/agents/ (just you).

Can Claude Code run multiple subagents in parallel?

Yes. Subagents Claude spawns start in the background and run concurrently, up to 20 at once by default.

What’s the difference between subagents and agent teams?

Subagents are helpers inside one session. Agent teams, an experimental feature, have a lead session spawn and supervise teammate sessions. Both serve one person.

Sources

Claude Code subagents and best practices (Anthropic), checked November 20, 2026.

Bring your agent. Bring your team.