10분 만에 394개의 서브에이전트가 Claude Code에서 나를 잠그게 했고, 그래서 먼저 물어보는 mod를 만들었다

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? submitted by /u/rbartoli [link] [comments]