Claude Code subagents explained (and why they burn your usage limit fast)

What a Claude Code subagent actually is

A subagent is a separate Claude Code worker your main session hands a piece of work to. It isn't a different product tier or a separate subscription, it's a delegation feature built into the tool itself. You define one as a markdown file with YAML frontmatter, a name, a description that tells Claude when to reach for it, an optional list of allowed tools, a model, and a handful of other settings, and drop it in .claude/agents/ for one project or ~/.claude/agents/ for every project you touch. From there, Claude Code treats it as a specialist it can call on, per Anthropic's own subagent documentation.

The main session decides when to delegate, and it usually does so on its own: Claude reads a subagent's description field and matches it against the task in front of it, the same way it decides when to reach for a tool. You can also force the issue, by naming the subagent directly in a prompt, by @-mentioning it, or by starting the whole session as that subagent with claude --agent code-reviewer. Either way, the subagent runs its own turn, does the work, and reports a summary back. The parent session sees the result, not the searching and reading that produced it.

How subagents run under the hood

Two things separate a subagent from just asking the main session to do the same task itself. The first is context. A fresh subagent starts with its own clean slate: its own system prompt, the delegation instructions it was given, the project's CLAUDE.md files, and any skills it was told to preload, but none of the parent conversation's history. The second is execution mode. A subagent can run in the foreground, blocking the main session until it finishes, or in the background, running alongside you while you keep working, with its own permission prompts surfacing in the main session under its name.

There's a third mode worth knowing if you've heard the word 'fork.' A forked subagent, started with /subtask or spun up automatically when fork mode is on, inherits the full parent conversation instead of starting clean. That's genuinely useful when a side task needs everything the main thread already knows. It also means a fork's starting context is at least as large as the parent's, so it's rarely the cheap option.

• Up to 20 subagents can run concurrently in one session by default, set by CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS; past that, a new one simply fails to spawn.
• Subagents can spawn their own subagents, nested up to 3 layers deep out of the box.
• The built-in /batch skill is a packaged example of heavy fan-out: it splits one large change into 5 to 30 worktree-isolated subagents, each opening its own pull request.
• Giving a subagent isolation: worktree in its frontmatter puts it in its own git checkout, so parallel subagents editing different files never collide.

Why fanning out subagents burns your usage window fast

This is the part that catches people off guard, and it's the same underlying system as Claude's usage limits generally: the 5-hour and weekly windows meter tokens processed, not tasks finished. A subagent doesn't get its own separate allowance. It draws from the exact same pool as the main session, and because every subagent keeps its own context window, running several at once doesn't just add their work together, it duplicates overhead, system prompt, project files, tool definitions, for each worker running in parallel. Anthropic says as much plainly in its own documentation: "Running several sessions or subagents at once multiplies token usage."

There's an actual number attached to a close relative of this pattern. Anthropic's cost-management docs put agent teams, where a lead coordinates several teammates sharing a task list, at roughly 7 times the token usage of a standard single-threaded session when those teammates run in plan mode, specifically because each teammate carries its own context window rather than sharing one. Plain subagent fan-out follows the same shape; Anthropic just hasn't published a specific multiplier for that exact case.

It's not hypothetical, either. In a report filed against Claude Code's own GitHub repository, a Max 20x subscriber described running 3 to 6 concurrent Opus subagents, an implementer and a reviewer per phase, over several hours of a long build, and hit a rate limit mid-session despite believing they had headroom left. Their real complaint wasn't that the limit existed. It was that nothing in the interface showed how fast parallel subagents were burning the pool until they'd already hit it. Claude Code's /usage command has since added an attribution breakdown showing what share of recent usage came from subagents versus the main session, which helps, but it's after-the-fact accounting, not a live warning while you're running.

What actually multiplies the burn

None of this makes subagents a bad idea. Splitting a big task into workers that each keep their own clean context is exactly why Claude Code built them, it keeps the main conversation from filling up with search results and file dumps you'll never look at again. The trade-off is that the same isolation keeping your main context tidy means every worker pays its own entry fee, and the usage meter adds it all up the same way whether one agent did the work slowly or five did it at once, quickly.

Keeping subagents from draining the window (and where a second lane fits)

• Cap concurrency on purpose. Lower CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS for background-heavy sessions instead of leaving the default of 20 in place.
• Put scoped, low-stakes subagents on a lighter model. Setting model: haiku in a subagent's frontmatter, or forcing it globally with CLAUDE_CODE_SUBAGENT_MODEL, keeps a lint-fixing or file-scanning worker off your most expensive model by accident.
• Check the /usage attribution breakdown before a big fan-out, not after. It shows what share of recent usage came from subagents specifically.
• Reach for fork mode deliberately rather than by default. A fork starts from a bigger context than a fresh subagent does, so it costs more per worker.

For the mechanics of the windows themselves, the rolling 5-hour session and the separate weekly cap stacked on top, Claude's usage limits guide covers that in full; this page is really about one specific way people run into it faster than expected. The other lever is which plan you're on in the first place: Claude Code's pricing guide breaks down what Pro, Max 5x, and Max 20x actually buy in session headroom, since a heavier subagent habit is one of the more common reasons people outgrow Pro.

Where a flat-rate second lane like NeverMetered fits is specifically in that overflow slot, the routine, high-volume side of subagent-shaped work: batch PR fixes through the /batch skill, a broad codebase audit run as a dynamic workflow, background subagents doing lint or test sweeps, not the hard problem a lead agent is actually reasoning through. NeverMetered prices by parallel streams instead of tokens, and Claude Code can point straight at its Anthropic-compatible API, so sending the overflow share of a fan-out there means concurrency doesn't chip away at a metered window at all: requests past your plan's stream count wait briefly in a queue instead of failing or draining a budget you can't see until it's gone. It runs Qwen3.8-27B behind that API, an open-weight model not pitched as a frontier one, which fits the volume side of a fan-out better than the reasoning your lead agent is doing on the hard part. See current plans for stream counts, or how NeverMetered compares.