Claude Code subagents: when to split the work
By Albert Nahas, 8 min read, updated
A Claude Code subagent is a separate Claude instance that your main session starts through the Agent tool. It gets a fresh context window, its own system prompt and its own tool list, and only its final summary comes back to you. You can write custom subagents as Markdown files with YAML frontmatter in .claude/agents/ (one project) or ~/.claude/agents/ (all your projects), and Claude hands work to one when the task matches its description.
That's how they work. Deciding when to use one is harder. I've run Claude Code every day for a long time, and scheduled agents now help me run my product OpenWhen. The most useful thing I've learned about subagents is that they cost more than they look like they will. This guide covers both halves.
What a subagent actually is
When Claude delegates, it calls the Agent tool. The tool was renamed from Task in v2.1.63, and Task(...) still works as an alias in permission rules. The subagent starts with:
- its own system prompt (the body of the agent file) plus some environment details
- the task message Claude wrote for it
- your CLAUDE.md files, unless it's Explore or Plan or the file sets
omitClaudeMd: true - a git status snapshot, again skipped for Explore and Plan
- any skills listed in its
skillsfield, preloaded in full
It does not see your conversation, the skills you invoked or the files you already read. Everything it knows about the task has to be in the brief Claude writes for it. Keep that in mind, because it's where most bad subagent runs go wrong.
When the subagent finishes, only its summary goes back to the main conversation. That's the whole point: twenty file reads and three failed greps stay in the subagent's context, not yours.
The built-in subagents
You get these without writing anything:
| Name | Tools or model | What it's for |
|---|---|---|
| Explore | Read-only (Write and Edit denied) | Codebase search, at quick, medium or very thorough depth |
| Plan | Read-only | Research while you're in plan mode |
| general-purpose | All tools available to subagents | Multi-step tasks that need to explore and act |
| claude | All subagent tools | Catch-all |
| statusline-setup | Runs on Sonnet | Configuring /statusline |
| claude-code-guide | Runs on Haiku | Questions about Claude Code itself |
Explore and Plan are one-shot. They return no agent ID, so you can't resume them. Other subagents can be resumed: Claude sends them a follow-up through the SendMessage tool, and they keep their full history.
Writing a custom subagent
A subagent is one Markdown file. Only name and description are required:
---
name: pr-grader
description: Grades a pull request against the merge policy. Use for every open PR before merging.
tools: Read, Grep, Glob, Bash
model: opus
maxTurns: 40
---
You are an independent reviewer. You have not seen the author's reasoning
and you should not ask for it.
Read the merge policy section of docs/OPS_LOOP.md, then the PR body and
the diff (gh pr view N, gh pr diff N). Judge the code, not the description.
Return exactly one grade (A, B, C or X) on the first line, then each
finding with file:line and the evidence. If you could not verify
something, say so instead of guessing.
The frontmatter fields I actually use:
| Field | What it does |
|---|---|
tools | Allowlist. Leave it out and the subagent inherits every tool subagents can use |
disallowedTools | Denylist, applied before tools |
model | sonnet, opus, haiku, fable, a full model ID, or inherit |
maxTurns | Hard cap on agentic turns. The output is marked partial and can be resumed |
permissionMode | default, acceptEdits, auto, dontAsk, bypassPermissions, plan |
isolation | worktree runs it in a temporary git worktree branched from your default branch |
memory | user, project or local persistent memory directory |
background | true keeps it in the background even when Claude would wait |
skills | Skills to preload in full at startup |
One trap: field names are camelCase and unknown fields are ignored without an error. If you write max_turns: 40, you get no cap and no warning, so check every new agent file against the docs table.
permissionMode has another catch. If your main session already runs in bypassPermissions, acceptEdits or auto mode, the subagent runs in that mode and ignores what you set. In those three modes the field can't take freedom away, so use tools and disallowedTools to restrict what the subagent can do.
Where they live
When two agents share a name, the higher-priority one wins:
- Managed settings (organization-wide)
- The
--agentsCLI flag, as JSON, for one session .claude/agents/in the project~/.claude/agents/for all your projects- A plugin's
agents/directory, under a scoped name likemy-plugin:code-reviewer
Project agents go in git so the whole team gets them. Personal ones go in ~/.claude/agents/. Cursor also reads .claude/agents/ for compatibility, so a well-written agent file works in both tools.
To force a specific agent, @-mention it (@agent-pr-grader) or name it in plain words: "use the pr-grader subagent on PR 212". To run a whole session as one agent, use claude --agent pr-grader.
When to split the work
This is the rule I keep in my global CLAUDE.md, almost word for word: a fresh agent knows only what you put in the prompt, and you see only the summary it sends back. Both handoffs drop detail, and neither side can tell what the other missed. Its mistakes come back sounding just as confident as its findings. An agent handed your hypothesis tends to return it confirmed.
So I use a subagent in three cases:
- Independent work that can run in parallel. Four modules to audit, three docs pages to verify, two data pulls that don't depend on each other. Subagents run in the background by default when Claude spawns them from the main conversation, up to 20 at once unless you change
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. - Reading across many files when I only need the conclusion. "Where do we set the session cookie, and who reads it?" is a perfect Explore job. I want the answer, not 40 file dumps in my context.
- A review that isn't anchored on my reasoning. This one matters most for unattended work, and I come back to it below.
When not to
Do it yourself when it's a handful of tool calls, or a lookup where you already know the target. Spawning a general-purpose agent to read one file you could open yourself costs a full context setup, plus a summary that may lose the one line you needed.
Don't delegate something and then also do it yourself "to be safe". You pay twice and end up with two answers to reconcile. Wait for the result.
And don't spawn several agents just because you can. They spend tokens in bursts, and the person paying didn't ask for a swarm. When in doubt, I don't spawn.
How to brief one so the result is trustworthy
The brief is the only context the subagent has. I write it the way I'd brief a peer joining mid-task:
Goal: find why /api/checkout returns 500 for gift purchases only.
Already ruled out: payment provider keys (other purchases work), the webhook
(the 500 happens before redirect).
Read: src/app/api/checkout/route.ts, src/lib/pricing.ts, and the
gift branch in src/lib/gifts.ts.
Scope: diagnose only, do not edit files.
Return: the failing line, the input that triggers it, and how you
confirmed it (command output or test), in under 150 words.
Four parts do the work: the goal, what's already ruled out (so it doesn't redo your work), where to look, and an explicit scope. Then ask for evidence, not just a conclusion. "How you confirmed it" turns a confident guess into something you can check in ten seconds.
If you can't write a brief that clear, you don't understand the task well enough to hand it off yet. I treat that as a signal to keep the work in the main thread.
The independent reviewer pattern
This is where subagents earned their place in my setup. Every pull request my agents open on OpenWhen goes to a reviewer subagent with fresh context. It reads only three things: the merge policy, the PR body and the diff. It never sees the author's reasoning, so it judges the code instead of agreeing with the argument for it.
That one rule is why I can let agents merge their own work. A reviewer that shared the author's context would wave through the same blind spots the author had. The grading rubric itself is in the PR review guide.
The detail that makes it work: give the reviewer the code, not your conclusion. "Check that this fix is correct" invites agreement. "Here is the diff and the policy, grade it" doesn't.
Running subagents unattended
When nobody is watching, the cheap safety controls matter more:
- Set
maxTurnson every custom agent. A subagent stuck in a loop then stops instead of burning your quota. - Keep
toolstight. A reviewer needs Read, Grep, Glob and theghcommands, not Edit. - Use
isolation: worktreefor agents that write code in parallel, so two of them never edit the same checkout. The worktree is removed automatically if the agent changes nothing. - Know the nesting limit. Subagents can spawn their own subagents up to three layers below the main conversation. Set
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1if you want no nesting at all.
If your workers need to talk to each other instead of reporting back to one coordinator, that's a different feature: agent teams, still experimental and enabled with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. My open-source TeamClaude adds a live dashboard and a manager/engineer sprint on top of it, because a multi-agent session you can't see into is hard to trust. For most work, plain subagents are enough and use fewer tokens.
What I'd do next
Write one reviewer subagent before any worker subagent. It's the agent that makes the others safe to run. Then read how I grade AI-reviewed PRs, and add hooks so the rules your subagents must follow are enforced by code, not just by the prompt.
Questions people ask
What is the difference between Claude Code subagents and agent teams?
A subagent works inside one session and reports its result back to the agent that spawned it. Agent teams are separate Claude Code sessions that share a task list and message each other directly. Teams are experimental, need CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1, and use more tokens.
Where do I put custom subagent files?
Put project subagents in .claude/agents/ and personal ones in ~/.claude/agents/. Each file is Markdown with YAML frontmatter, and only name and description are required. If two agents share a name, the project one wins over the user one.
Is the Task tool the same as the Agent tool?
Yes. The Task tool was renamed to Agent in Claude Code v2.1.63, and Task(...) still works as an alias in permission rules and settings.
Can a subagent see my conversation history?
No. A subagent starts with a fresh context: its own system prompt, the task message Claude wrote, CLAUDE.md files and a git status snapshot. Anything else it needs has to be in the brief.
Can Claude Code subagents use a different model?
Yes. Set model in the frontmatter to sonnet, opus, haiku, fable, a full model ID, or inherit. Leave it out and the subagent uses the main conversation's model unless CLAUDE_CODE_SUBAGENT_MODEL is set.
How do I stop a subagent from running too long?
Set maxTurns in its frontmatter. When it hits the cap it stops, marks its output as partial, and can be resumed later.