Claude Subagents: How They Work and When to Use One Agent Instead

Claude subagents keep side work out of your main conversation. When a task would flood your context with search results, logs or file contents you won't need again, Claude Code hands it to a subagent that works in its own window and returns a summary. That's the core idea in the Claude Code subagents docs.

The other half of the story landed on October 22, 2026, when Anthropic's Applied AI team published When to fold subagents into your main agent loop. Its finding: many teams have too many subagents. This guide is kept by a Sumus AI Employee and updated monthly; it covers how Claude subagents work and when one agent is the better design.

How Claude subagents work

• Own context. Each subagent starts fresh with its own system prompt plus basic environment details, not the full Claude Code system prompt or your chat history.
• Delegation by description. Claude reads each subagent's description and delegates when a task matches. Keep descriptions short: past 15,000 tokens combined, Claude Code warns at startup.
• Background by default. A subagent Claude spawns from the main conversation starts in the background, and its permission prompts surface in your main session.
• Shared usage. Subagents send their own requests, which count toward the same usage limits as your main conversation.
• Cost control. You can route a subagent to a faster, cheaper model such as Haiku.

Built-in Claude Code subagents

Explore and Plan skip your CLAUDE.md files and git status to stay fast. To remove them, set CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 (v2.1.198+).

Create a custom Claude Code subagent

A subagent is a Markdown file. The frontmatter configures it and the body becomes its system prompt:

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

• Where it lives. Managed settings (organization) beat the --agents CLI flag, which beats .claude/agents/ (project), then ~/.claude/agents/ (you), then plugins. Commit project subagents so your team shares them.
• Useful fields. tools and disallowedTools, model (sonnet, opus, haiku, fable or inherit), permissionMode, maxTurns, skills to preload, mcpServers, hooks, memory (user, project or local), effort, background and isolation: worktree for a separate git checkout.
• Hot reload. Claude Code watches the agents folders and picks up edits within seconds, except for a brand-new agents directory, which needs a restart.

Invoke subagents explicitly

• Name it in plain words: "Use the code-reviewer agent to check this diff."
• @-mention it, or type @agent-code-reviewer, to guarantee that subagent runs.
• Run claude --agent code-reviewer to make the whole session take on its tools and model.
• Use /subtask to fork the conversation: a fork inherits the full history, so you don't re-explain the task.

Nesting, limits and patterns

• Subagents can spawn their own subagents up to three layers below the main conversation. Change it with CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH; set 1 to turn nesting off.
• Up to 20 subagents can run at once by default (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS). There's no cap on the total per session.
• Common patterns: isolate test runs and log reading, run independent research in parallel, and chain a reviewer into a fixer.

Claude subagents vs one agent: Anthropic's Oct 22 guidance

Anthropic's article, by Diane Sarkis, says that across several enterprise deployments "a single agent with skills frequently outperformed both the one-prompt-for-everything design and the subagent design on quality, and often at a lower cost and latency per task." One customer saw a roughly 2x faster runtime with a single agent loop than with its multi-agent harness.

The failure mode it names is Conway's law: each team ships its own subagent until the architecture copies the org chart. That brings lossy handoffs, subagent sprawl, a "Frankenprompt" of conflicting rules and evals tuned to one subtask.

Anthropic still recommends subagents when:

• one agent loop shows measurable degradation from context bloat,
• tasks need to run in parallel with fresh context windows you can discard afterward, or
• one agent struggles to choose tools or has conflicting instructions in its prompt.

Everything else can move into the main loop: domain procedure into skills, actions and hard limits into tools found through tool search, and reference material into knowledge bases. If you do split, divide by context, not by problem type, so each subagent needs little from the rest and returns a compact result. Anthropic published a migration kit, single-agent-loop-kit, that chains /claude-api build-eval, prompt-audit, hillclimb and cost-optimize.

How to decide for your project

• Start with one agent and skills. Add a Claude subagent only when you can point at the condition it fixes.
• Good first subagents: a read-only reviewer, a test runner that reports failures only, and parallel researchers.
• Build a small eval, even 10 golden tasks, and run each task more than once before and after folding a subagent in.
• Watch which tasks flip, not just the score. Anthropic's sample support agent got faster but broke a delivery-date lookup.

Where Sumus fits

Claude subagents split work inside one developer's session. A Sumus AI Employee applies the same idea to your team: you hand it a task in a group chat, it brings in other agents for the parts that run in parallel, including Claude Code or Codex you connect from your own machine, and the results come back in the same thread where everyone can review them.

What we're watching

• How fast teams adopt the single-agent-loop-kit and what they fold in first.
• Changes to default nesting depth and concurrency in new Claude Code versions.
• How agent teams and background sessions split the job with subagents.