Claude Code subagents: when to split work off

Claude Code subagents are worth using when a side task would flood your main conversation with search results, logs, or file contents you won’t reference again. The subagent does that work in its own context and returns only the summary.

This guide covers what a subagent is, the built-in ones, how to write your own as a Markdown file, where to save it, and the limits that apply. It follows the Claude Code subagents documentation and uses the built-in Explore, Plan and general-purpose subagents plus one custom reviewer.

1. Decide if the task needs its own context window

A subagent is a specialized AI assistant that handles one type of task. Each subagent runs in its own context window with a custom system prompt, specific tool access, and independent permissions.

Ask one question: will you read the raw output again? If the answer is no, as with a codebase search or a long log, split it off. If you will keep working with the output, keep it in the main conversation.

Splitting does not save quota. A subagent sends its own requests, which count toward the same usage limits as your main conversation. What you buy is a cleaner main context, not a cheaper session. For what spends your limits, see Claude Code usage limits.

Subagents work within a single session, so other shapes of work need other tools:

2. Know the built-in subagents

You may not need to write anything. Claude Code includes built-in subagents that Claude automatically uses when appropriate.

Explore and Plan start without your CLAUDE.md files and the git status snapshot to keep research fast and inexpensive. Other subagents load both. When Claude calls Explore, it picks a thoroughness level:

3. Create your first subagent

Define a custom subagent when you keep spawning the same kind of worker with the same instructions. Subagents are Markdown files with YAML frontmatter, and you can ask Claude to write the file for you. In Claude Code, describe it and say where to save it:

# A prompt typed into Claude Code, from the Claude Code docs quickstart
Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Then open the saved file and check that it matches what you asked for. The docs show this result:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Try it by asking Claude to use the code-improver agent on your project. The delegation appears as a tool call row showing the subagent’s name followed by a short task description. If Claude can’t find the new subagent, restart Claude Code. This happens only when ~/.claude/agents/ didn’t exist before the session started.

4. Read the frontmatter fields

Only two fields are required, name and description. The rest narrow what the subagent can do.

To keep a worker read-only without listing every allowed tool, deny the writers instead:

disallowedTools: Write, Edit

5. Pick where the file lives

The file location decides who can use the subagent. When multiple subagents share the same name, Claude Code uses the one from the higher-priority location.

Project subagents suit one codebase, and checking them into version control lets your team use and improve them collaboratively. User subagents in ~/.claude/agents/ follow you across projects. If you already keep shared skills in one place, sharing one skills repo between Claude Code and Codex covers that side.

The --agents flag takes the same fields as JSON, for a subagent that lasts one session and writes no file:

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

6. Keep descriptions short and tools narrow

Claude uses each subagent’s description to decide when to delegate tasks, so write a clear one. Descriptions also take up context. When the combined descriptions of your subagents, except the built-in ones, exceed 15,000 tokens, Claude Code shows a warning at startup with the total token count. Trim the description and move detail into the system prompt, which only loads when that subagent runs.

Two more levers matter:

• Tool limits. You can enforce constraints by limiting which tools a subagent can use, as the read-only reviewer above does.
• Model choice. You can control costs by routing tasks to faster, lower-cost models like Haiku.

To force one model on every subagent, set two environment variables in a settings file:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

7. Know foreground and background runs

With nothing configured, a subagent that Claude spawns from your main conversation starts in the background. The two modes differ in what the main conversation sees.

8. Stay inside the limits

Four numbers decide how far a set of subagents can grow:

At the concurrency limit, spawning another subagent fails with Concurrent subagent limit reached. A subagent can also set its own autoCompactWindow, a token count from 100000 to 1000000.

9. Repeat it for each recurring task

Each time you notice the same side task flooding your main conversation, run the same loop:

1. Name the task and confirm you won’t reread its raw output.
2. Check whether a built-in subagent already covers it.
3. If not, ask Claude to write a subagent with a short description, the fewest tools it needs and a model sized to the job.
4. Save it in the project folder if the team shares it, or in your user folder if only you do.
5. Ask Claude to use it by name and watch for the tool call row.

Verdict

Split work off when the output is bulky and you won’t reference it again, and keep it inline when you will. Expect a cleaner main context, not a lighter bill, because subagent requests count toward the same usage limits. Start with the built-in Explore and Plan subagents, then write your own once you repeat the same instructions.

Try it: define your first subagent in the Claude Code docs