Do Claude Code Subagents Burn Your Usage Limit Faster? (2026)

You spawned four subagents to review a PR from four angles. Twenty minutes later Claude Code told you that you hit your weekly limit. Nothing you typed was expensive. The agents were.

This post covers the subagent and agent team mechanics specifically. For the general limit mechanics (rolling 5-hour window, weekly window, why a long session costs more than a hard question), read Stop Hitting Claude Code Usage Limits first. This one assumes you already know that.

The four mechanics that decide the bill

1. Every subagent has its own context window

Anthropic documents this at code.claude.com/docs/en/sub-agents: a subagent runs in its own isolated context window, and that window is sized by the subagent’s own model, not the parent’s. A non-fork subagent does not inherit your conversation history.

Fresh is not free. A non-fork subagent still loads, at startup:

• its own system prompt plus environment details
• the task message your main agent wrote
• every level of the CLAUDE.md hierarchy (Explore and Plan skip this)
• a git status snapshot from the parent session start
• the full content of any skills named in the agent’s skills field
• the roster of other named agents in the session

So a 400-line CLAUDE.md is not paid once per session. It is paid once per subagent, every time one spawns. That is the single most common surprise.

A fork is the exception, and it is the cheap one. A fork inherits the entire conversation so far instead of starting fresh. Because its system prompt and tool definitions are identical to the parent’s, the docs say its first request reuses the parent’s prompt cache, which makes forking cheaper than spawning a fresh subagent for tasks that need the same context. The tradeoff is size, not startup price: a fork begins with your whole conversation in its window and every one of its turns resends that, so a fork of a large session is an expensive agent to run even though it is a cheap agent to start.

2. Every subagent turn resends that subagent’s whole context

This is the same mechanic that makes long main sessions expensive, running in parallel copies. Anthropic documents it for sessions: Claude Code sends your full conversation with every request, and each time Claude uses tools it sends another request carrying that batch of tool results (costs docs). The docs do not restate it for subagents, but a subagent is a conversation with its own context window, so a subagent that makes 30 tool calls resends its growing context 30 times. Prompt caching lowers the rate on the repeated part; it does not shrink it.

A subagent that runs long is not cheap because it is “just a helper”. It is a second session, billed like one.

3. Only the summary comes back, and that is the actual saving

When a subagent finishes, its result returns to the parent conversation. The verbose middle does not. Anthropic’s wording: “the verbose output stays in the subagent’s context while only the relevant summary returns to your main conversation” (sub-agents, costs).

That is the entire economic case for subagents. A subagent is cheaper than the main thread only when the work generates far more intermediate output than final answer. A 200MB-of-log-lines job that ends in “5 tests failing, here is which” is the shape that pays. Test runs, log processing, doc fetching, wide codebase searches. Anthropic does not publish token figures for the tradeoff, so the only way to see it in your own setup is /context before and after.

Two details that change how you plan around it: background subagents return their result as a completion notification in a later turn, and the built-in Explore and Plan agents are one-shot, so they cannot be resumed.

4. Parallelism multiplies, it does not amortize

Claude Code runs up to 20 concurrent subagents by default (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), nested up to 3 layers deep (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Nothing is shared between them. Ten parallel agents each carry their own CLAUDE.md, their own tool results, and their own growing history.

Parallel agents buy you wall-clock time. They do not buy you tokens. If your complaint is “I hit the limit far sooner than expected”, concurrency is usually the reason, and it is the one thing that scales your burn linearly with no ceiling except the concurrency cap.

Agent teams are a different, larger cost

Agent teams are not subagents with messaging bolted on. Each teammate is a separate Claude Code instance with its own context window, and they message each other directly instead of only reporting back.

Anthropic’s own comparison:

The number to know: agent teams use approximately 7x more tokens than a standard session when teammates run in plan mode, per the costs page. That is a documented figure with a stated condition, so treat it as the plan-mode case, not a universal multiplier.

Teams are also off by default. They need CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1. Worth knowing: the docs state that Claude names subagents on its own so it can message them later, and while teams are enabled, a named subagent launches as a teammate. You can end up paying team prices for delegation you never framed as team work. It also changes what comes back. A subagent hands Claude its result; a teammate sends an idle notification that reports it stopped and carries none of its output, so an orchestration waiting on a result can stall. Set the variable to 0 to get subagents back. No restart needed: Claude Code rereads it each time it spawns one.

Two more team-specific drains, both documented:

• Idle teammates keep costing. Each active teammate consumes tokens until it exits or the session ends. Shut them down by name when their work is done.
• Spawn prompts are permanent context. Teammates load CLAUDE.md, MCP servers, and skills automatically, so everything you add to the spawn prompt is on top of that, from turn one, for the whole run.

The levers, in order of payoff

1. Route subagent work to a cheaper model

The model field in a subagent definition accepts an alias (sonnet, opus, haiku, fable), a full model ID, or inherit. If you omit it, it defaults to inherit, which means your grunt-work agents are running on whatever the main session runs on. That is the default most people never change.

Resolution order, first match wins: the CLAUDE_CODE_SUBAGENT_MODEL environment variable, then a per-invocation model parameter, then the definition’s frontmatter, then the main conversation’s model.

---
name: log-scanner
model: haiku
tools: Read, Grep, Glob, Bash
---

The gap is real. At Claude API list rates as of August 2026 (pricing), Haiku 4.5 is $1 per million input tokens and $5 per million output, Sonnet 5 is $3 and $15, and Opus 5 is $5 and $25. A grep-and-report agent on Haiku instead of Opus is a fifth of the input cost for work where the model choice does not change the answer. One thing to size for: context windows come from the model too, and Haiku 4.5 is a 200K window against 1M on Sonnet 5 and Opus 5. A Haiku agent pointed at a huge log is the wrong tool, not a cheaper one.

One caveat on subscription plans: those are API dollar rates. Anthropic does not publish how plan limits convert token usage into your 5-hour and weekly allowance, and the mapping is not documented anywhere primary. What is documented is that the windows are shared across all models, so switching models does not reset them. Model routing reduces the tokens you spend; the exact effect on your bar is not something anyone outside Anthropic can state precisely.

CLAUDE_CODE_SUBAGENT_MODEL is the fastest test, because it overrides every definition at once. Set it to haiku for a day and watch /usage.

2. Cut CLAUDE.md, because you pay it per agent

Anthropic recommends keeping CLAUDE.md under 200 lines and moving specialized instructions into skills, which load on demand. In a single-session workflow that is a modest saving. In a subagent-heavy workflow it multiplies by the number of agents you spawn. This is the highest-leverage edit for anyone running fan-out work.

Same logic applies to the skills frontmatter field: preloaded skills load in full at subagent startup. Only preload what the agent genuinely needs.

3. Keep the spawn prompt narrow, and the tool list narrower

Give each subagent one deliverable and the smallest tool set that can produce it. Use the allowlist or denylist in the definition:

---
name: safe-researcher
tools: Read, Grep, Glob, Bash
---

---
name: no-writes
disallowedTools: Write, Edit
---

A read-only research agent that cannot edit will not spend a turn attempting an edit and recovering from the refusal. Narrow tools are a cost control, not only a safety control. Both fields accept server-level MCP patterns, documented as mcp__<server> or mcp__<server>__*, so disallowedTools: mcp__github removes every tool from that server at once. If both fields are set, disallowedTools is applied first and tools resolves against what is left.

4. Know when a subagent is pure overhead

Use one when the work produces a lot of intermediate output and a small answer:

• running a test suite and reporting failures
• scanning logs for a pattern
• fetching and summarizing documentation
• searching an unfamiliar codebase for where something lives

Skip it when:

• the task is small enough that the answer and the intermediate output are the same size. You pay a fresh CLAUDE.md and startup context to save nothing.
• the agent needs a couple of facts from your conversation and you reach for a fork to carry them. A fork starts cheap because it reuses the parent’s cache, but it starts big, and every turn it takes resends the whole inherited history. A 5-line briefing in a normal subagent is smaller to run.
• the work is sequential, edits the same files, or is dependency-heavy. Anthropic’s own guidance is that a single session or plain subagents beat a team here.
• you are running agents in parallel purely for speed on work you are not in a hurry for.

5. Measure it instead of guessing

/usage on a Pro, Max, Team, or Enterprise plan shows recent usage attributed to skills, subagents, plugins, and individual MCP servers, each as a percentage of the total. Press d or w to switch between the last 24 hours and the last 7 days. It also raises behavior flags for things like long context or cache misses when one accounts for 10% or more of recent usage.

Two limits worth knowing before you trust the number: the figures are approximate and computed from local session history on that machine, so other devices and claude.ai are not included. And on a subscription, the dollar figure in the Session block is priced at standard list rates for API users. It is not your bill.

What to do this week

1. Run /usage, press w, and read the subagent attribution line. If it is a large share, the rest of this list is worth doing.
2. Set CLAUDE_CODE_SUBAGENT_MODEL=haiku for a day of routine delegation and compare.
3. Cut CLAUDE.md toward 200 lines. You pay it once per agent, not once per session.
4. Add an explicit model: to every subagent definition you own. inherit is the default and it is rarely what you want for grunt work.
5. If agent teams are on and you did not deliberately turn them on, check CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS. Named subagents become teammates while it is enabled.
6. Shut down idle teammates by name. They cost tokens until they exit.

The same discipline applies to single long sessions, where the fix is a clean restart with a handoff doc rather than a growing context. That case is covered in Restart Claude Code Sessions at 200K Tokens. If you are deciding which agent work belongs on a paid frontier model at all, Hybrid Routing covers the split, and AI Agent Cost per Task covers how to put a real number on a completed task.