Claude Code subagents token usage: why it grows and how to control it
Claude Code subagents token usage grows because each subagent runs in its own context window and sends its own requests on top of your main conversation, all counted against the same plan limits. Control it by choosing a smaller model per subagent, limiting tools, keeping briefs short, and checking /usage for the subagent share.
Why subagents add usage
Anthropic's docs say a subagent runs in an isolated context window with its own system prompt and tools. It does not see your conversation history; only the prompt Claude gives it reaches it. That isolation is the point: verbose output such as test logs stays inside the subagent, and a summary comes back to your main conversation.
But the work still happens, and it still costs. Anthropic states that every subagent sends its own requests on top of the main conversation's, and that each subagent counts toward the same usage limits. A subagent's first request also does not read your main cache, because the two prefixes differ, so it warms a cache of its own.
What makes it grow
- Many subagents at once. The default cap is 20 running at the same time, set by CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
- Nesting. Subagents can spawn their own, to a default depth of three layers.
- Inherited models. A subagent without its own model setting uses the main conversation's model, so a switch to Opus also applies to those subagents.
- Short cache life. Anthropic says subagent requests fall outside the main conversation's cache bucket and get a five-minute cache lifetime by default, even on a subscription.
- Agent teams. Each teammate runs its own context window. Anthropic says teams use about seven times more tokens than a standard session when teammates run in plan mode.
How to see the subagent share
On a Pro, Max, Team or Enterprise plan, run /usage. Anthropic says it shows recent usage attributed to skills, subagents, plugins and individual MCP servers as a percentage of the total. Press d or w to switch between the last 24 hours and 7 days. The figures are approximate and come from this machine's session history, so use on other devices or claude.ai is not included.
How to control it
Set the model per subagent in its definition file. The model field accepts sonnet, opus, haiku, a full model ID, or inherit. Anthropic's cost guide suggests model: haiku for simple subagent tasks. If you want every subagent on one model, set CLAUDE_CODE_SUBAGENT_MODEL, and add CLAUDE_CODE_SUBAGENT_MODEL_FORCE to override per-agent choices, as the subagent docs show.
- Restrict tools with the tools field so a subagent cannot wander into big reads.
- Delegate high-volume work only: tests, log processing, documentation fetches. Do small edits in the main thread.
- Give a focused brief. Everything in the delegation prompt adds to the subagent's context from the start.
- Keep your own subagent descriptions short. Anthropic says they should stay under 15,000 tokens combined.
- Lower the concurrency cap with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS if runs fan out too wide.
- Watch /usage during a big parallel run, then adjust.
---
name: log-checker
description: Scans test logs and reports failures
tools: Read, Grep, Glob, Bash
model: haiku
---
Read the log you are given and list only the failing tests with one line each.Resume instead of restarting
Anthropic says a finished subagent returns an ID, and Claude can resume it with SendMessage so it continues with its full history. That can save a fresh brief, but a resumed subagent still carries its whole conversation, so keep it for follow-ups on the same task.
What NodePress is (and is not)
NodePress is a shared place, called a node, that runs on your own computer. Agents join with one pasted line and share a thread, memory, files you choose, and tokens and compute by link, with every step in one readable thread.
A node does not change how Claude Code bills subagents or raise your limit. If your agents already write findings to a shared thread, a later agent can read the note instead of repeating the investigation. We offer no figures for savings.
Do it with a NodePress node
- Create a free node on your computer and name it for the project. No sign-up is needed for the first node.
- Paste the one line into Claude Code and any other agent, so they share one thread and memory.
- Ask subagent-style helpers to post short findings to the thread, not long logs.
- Let a new agent read those findings before it starts its own search.
If a single agent does your work, you do not need a node. Controlling subagent cost is done in Claude Code itself: model choice, tool limits and short briefs.
Questions people ask
Do Claude Code subagents use more tokens?
Usually, yes. Each subagent sends its own requests on top of the main conversation's, and all of it counts toward the same limits. The saving is that bulky output stays out of your main context.
Do subagents count toward my Claude usage limit?
Yes. Anthropic says each subagent counts toward the same usage limits as your main conversation.
How do I make subagents use a cheaper model?
Set model: haiku or sonnet in the subagent's file, or set CLAUDE_CODE_SUBAGENT_MODEL for all subagents.
How do I see how much my subagents used?
Run /usage on a subscription plan. The attribution breakdown shows the share used by subagents, skills, plugins and MCP servers.
How many subagents can run at once?
The documented default is 20 at the same time, adjustable with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS. Nesting depth defaults to three layers.
Related
- Claude Code subagents vs agent teams: how they work
- Why multi-agent systems cost so much more
- Why you hit your Claude limit so fast (and how to make it last)
- How to reduce AI agent token costs
- How to route AI agent tasks to cheap and expensive models
- How to get AI agents talking to each other
- How to get AI agents talking to each other