← sources

394 subagents in ten minutes locked me out of Claude Code, so I built a mod that asks first

source: reddit (reddit:ClaudeAI)published 2026-10-09 17:19ingested 2026-10-10 02:35

retained text


One afternoon I gave Claude Code a research prompt at max effort. It made 394 subagent calls, 341 of them running at once, and pushed 84M context tokens through the API in ten minutes. Then "Claude usage limit reached": locked out until the window reset. Sixty days of my logs held 12 lockouts like it.

So I built agent-usage-guard, a Claude Code mod (mods are the in-process hooks Claude Code added in 2.1.287). It acts before the spend, not after:

- **Agents:** 4 running at once and 12 starts per 10 minutes, counted across every Claude Code session on your 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. A heavy session resumed after its prompt cache expired asks too.
- **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 the condition until it clears, so the same question doesn't come back call after call. In `claude -p` it refuses with a reason instead, so Claude can wait, batch the work or stop. `/agent-guard report` shows what it did.

The video is Claude Code's real UI running against a scripted local API: the sessions and token counts are staged, and no usage was spent recording it.

**How I built it:** with Claude Code, in TypeScript with no dependencies; 86 tests run in Claude Code's own mod test kit. Its first version was plain hooks, which I ran for 75 days: my largest agent burst fell from 365 starts in ten minutes to 27. It hasn't cut my lockouts yet. Those come from many main sessions running in parallel, which is what I'm working on next.

Free, MIT, no network calls. Install 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

Which default would you change first?

document fetched 2026-10-10 00:22 · canonical https://reddit.com/r/ClaudeAI/comments/1x1r82v/394_subagents_in_ten_minutes_locked_me_out_of