claudekit / guides / subagents
[ Guide · Advanced · 10 min ]

Splitting Work with Subagents

published · updated

How to split work with subagents to keep your main context clean and run tasks in parallel. Covers when subagents help and how to define your own.

What subagents solve

Long sessions hit these inefficiencies:

  • Search results and log dumps eat the main context’s token budget
  • Self-review by the main agent is biased — it tends to agree with its own work
  • Independent tasks run sequentially, wasting wall-clock time

Subagents are helper agents in their own context. Only the result returns to the main conversation, keeping context clean. They also run in parallel.

Define a subagent

A subagent is a markdown file with frontmatter. Where you put it sets its scope and priority:

LocationScopePriority
Managed settingsOrganization-wide1 (highest)
--agents CLI flagCurrent session2
.claude/agents/Current project3
~/.claude/agents/All your projects4
Plugin’s agents/ directoryWhere plugin is enabled5 (lowest)

When multiple subagents share the same name, Claude Code uses the one from the higher-priority location. The /agents wizard was removed in Claude Code 2.1.198; ask Claude to create or manage subagents, or edit .claude/agents/ directly.

Example .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: |
  Use after a logical chunk of code is written to review it against
  the original plan and project coding standards.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. Given a recent change set, identify:
1. Bugs and logic errors
2. Security vulnerabilities
3. Deviations from project conventions

Report only high-confidence issues. Skip stylistic nitpicks.

Frontmatter fields

Only name and description are required.

FieldPurpose
nameUnique identifier used to invoke (required)
descriptionWhen Claude should delegate to this subagent (required; same role as a Skill’s description)
toolsTools the subagent can use. Inherits every tool available to subagents if omitted
modelsonnet, opus, haiku, fable, a full model ID such as claude-opus-5-5, or inherit. When omitted, Claude Code falls back to CLAUDE_CODE_SUBAGENT_MODEL, then the main conversation’s model

Other supported fields include disallowedTools, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation, and color. Multi-word fields use camelCase, and Claude Code ignores a field it doesn’t recognize without reporting an error, so watch for typos.

How to invoke

Auto-invocation

When the description matches the situation, the main agent calls the subagent automatically via the Agent tool.

Explicit

Name the subagent in natural language, or @-mention it:

Use the code-reviewer agent to review src/auth/
@"code-reviewer (agent)" look at the auth changes

To run a whole session as a subagent, use claude --agent code-reviewer. To make it the default for a project, set { "agent": "code-reviewer" } in .claude/settings.json. The CLI flag overrides the setting if both are present.

Parallel

In parallel:
- code-reviewer on src/auth/
- security-auditor on dependency vulnerabilities
- test-coverage-analyzer on missing test areas

A subagent that Claude spawns from your main conversation starts in the background by default. Claude keeps working while they run and is notified as each one finishes. By default, 20 subagents can run at once in a session; set CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS to change this.

Forks and nesting

  • Forks — a fork inherits the parent conversation instead of starting fresh. Forks are on by default; set CLAUDE_CODE_FORK_SUBAGENT=0 to turn them off.
  • Nesting — by default, a subagent can spawn subagents of its own, up to three layers below the main conversation. Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to turn nesting off.

When to use vs skip

Good fitSkip
Code reviews (independent perspective)Next step in main work
Broad search and explorationNeeds user interaction
Security or perf auditsNeeds shared progress
Concurrent multi-area analysisShort, simple questions
Isolating long output from main contextOutput drives main decisions immediately

Writing a good description

Auto-invocation depends on description quality.

Good

description: |
  Use after writing or modifying code in a logical chunk
  (a feature, a bugfix, a refactor) to review the change against
  the original plan and project coding standards. Reports
  high-confidence issues only.

Bad

description: Reviews code  # too vague — won't trigger reliably

Restrict tools

The tools field limits what a subagent may use:

tools: Read, Grep, Glob   # read-only — cannot modify code

Review and audit agents typically run safest as read-only. To remove specific tools from the inherited set instead, use disallowedTools.

Patterns

Pattern 1: protect main context

For long search results or logs, delegate to a subagent and only get the summary back. The built-in Explore subagent is a fast, read-only agent optimized for searching and analyzing codebases.

Use the Explore agent to find 'authentication' across src/ and report the locations and patterns in 200 chars.

Pattern 2: independent review

Self-review introduces bias. Ask a subagent for an independent take.

Use the code-reviewer agent to independently assess if my recent migration is safe. Don't agree with my analysis — judge on its own.

Pattern 3: parallel analysis

In parallel:
- agent-A on X
- agent-B on Y
- agent-C on Z

Next steps

  • Superpowers — includes skills built on subagents, such as subagent-driven-development and dispatching-parallel-agents (the superpowers:code-reviewer agent was removed in v5.1.0)
  • Code Review, PR Review — review-focused agent collections
  • Build a Skill — standardize subagent invocation via Skills
  • Subagents docs — full frontmatter reference and current behavior
§ 9

Frequently Asked Questions

frequently asked
§ 9.1
What is a subagent?
A helper agent that runs in a separate context from the main conversation. Delegate independent work, searches, or reviews to it to keep the main context clean — and run several in parallel to cut wall-clock time.
§ 9.2
When should I use a subagent?
Independent work where you only need the result (code reviews, broad searches, security audits) is a perfect fit. Skip subagents for collaborative tasks that need the main conversation's evolving state.
§ 9.3
How do I define one?
Create `<agent-name>.md` in `.claude/agents/` for the current project, `~/.claude/agents/` for all your projects, or a plugin's `agents/` directory. Only `name` and `description` are required in the frontmatter; add `tools`, `model`, and other fields as needed, and write the system prompt in the body.
§ 9.4
Can I run several subagents in parallel?
Yes. With nothing configured, a subagent that Claude spawns from your main conversation starts in the background, so several run concurrently while Claude keeps working and is notified when each finishes. By default, 20 subagents can run at once in a session.
§ 9.5
How are subagents different from plugins?
A Plugin is a package of slash commands, hooks, and skills (and may include subagents). A subagent is an executable worker that can live inside a plugin or stand alone.