← sources

Claude Code's subagent limits are per session, so I built a mod that counts across all of them

source: reddit (reddit:ClaudeCode)published 2026-10-11 22:52ingested 2026-10-12 02:39

retained text

Claude Code stops a session at 20 subagents running at once and three levels of nesting. Nothing counts across sessions, nothing caps how many a session starts over time, and nothing checks how much of your 5-hour window is left before an agent starts.

Before even those limits existed, one research prompt of mine made 394 subagent calls and pushed 84M tokens through the API in ten minutes. I was locked out until the window reset.

**agent-usage-guard** is a Claude Code mod (the in-process hooks added in 2.1.287). It holds the rest before the spend:

- **Agents:** 4 running at once and 12 starts per 10 minutes, counted across every Claude Code session on the machine. Subagents can't start their own.
- **Plan window:** from 80% of your 5-hour or weekly window, new agents ask first. From 95% they're refused.
- **Heavy context:** a prompt that would re-read 500k+ tokens asks to compact first, send anyway, or cancel.
- **Loops:** after three identical failures in a row, the identical retry is refused.

It asks in Claude Code's own question dialog, and one approval covers that condition until it clears. In `claude -p` it refuses with a reason, so Claude can wait or batch the work. `/agent-guard report` shows what it did.

**How I built it:** with Claude Code, in TypeScript with no dependencies. The tests run in Claude Code's own mod test kit (`claude plugin test`), which fires real hook events with no session, model or network behind them.

**What I learned:**

- **Starting the 394 agents wasn't the expensive part.** Each one's first request was about 29k tokens, so the starts came to about 10M, an eighth of the total. The rest was the agents working.
- **Mod events don't cover every path yet.** A `/subtask` fork starts without `agent.spawn`, so the guard can count it but not hold it.
- **Agents weren't what kept locking me out.** The first version, plain hooks that I ran for 75 days, cut my largest burst from 365 starts in ten minutes to 27, and the lockouts kept coming. Before each one, a median of 12 main sessions had been running, and no rule holds those yet. A note at 95% telling each session to wrap up is next.

Free, MIT, no network calls. In Claude Code 2.1.287+:

```
/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins
```

https://github.com/rbartoli/agent-usage-guard

If you run a lot of sessions in parallel, what should it do when the window hits 95%?

document fetched 2026-10-12 00:34 · canonical https://reddit.com/r/ClaudeCode/comments/1x3lx5o/claude_codes_subagent_limits_are_per_session_so_i