Agent-usage-guard holds Claude Code's agents before they drain the plan

A single Claude Code prompt can spawn hundreds of subagents, and the window on a Max plan ends in silence a few minutes later. The author of agent-usage-guard, published on GitHub and launched on Hacker News on 22 October with 22 points, says one of his own research prompts spawned 394 subagent calls, 341 of them running at once, and pushed 84 million context tokens through the API in ten minutes before Claude Code told him the usage limit was reached.

The project is a MIT-licensed TypeScript mod for Claude Code, installed through the plugin marketplace with /plugin marketplace add rbartoli/agent-usage-guard and /plugin install agent-usage-guard@agent-usage-guard. It requires Claude Code v2.1.287 or later. The repository holds 45 stars at the time of writing.

What it watches

The mod reads the 5-hour and weekly plan percentages from Claude Code's API responses and holds work when a window is nearly full. Its defaults ask the user to approve any new agent once a window passes 80% and refuse once it passes 95%. It also asks when the 5-hour window rises more than 20 points in 10 minutes, the author's test for a runaway.

Separate rules cover the three failure modes the author names: fan-out, heavy context, and retry loops. By default the mod asks before a fifth agent runs at once across every session on the machine, before more than 12 agent starts in 10 minutes, before subagents push more than 10 million tokens in 10 minutes, and refuses when a subagent would spawn its own agent. For context, it asks before a prompt would re-read more than 500,000 tokens, before 20 tool calls in 10 minutes at a 400,000-token context, and before a heavy session re-writes its prompt cache after an hour idle. For loops, it refuses a tool call that has failed three times with no other call between.

How it asks

When the user is at the keyboard, the mod uses Claude Code's own question dialog. An approval lifts the condition until the window resets or the context shrinks, so the user is not asked again on every tool call. A decline tells Claude to stop starting agents for 10 minutes, and the model is told the reason in words so it can wait, batch the work, or stop. In headless mode (claude -p, the Agent SDK, or dontAsk mode) the mod refuses the call and gives the reason as the tool result, so the model reads it like any other refusal.

What it will not touch

The author is explicit about where the mod does not get in the way. It never holds a background task's notification or another session's message, because that would lose the result. It no longer blocks prompts at the usage limit itself, because Claude Code v2.1.234 and later wait at the limit and continue at reset on their own; the mod's role is to prevent the lockout before it happens. From 95% of a window, each session's next prompt only gets a note telling Claude to finish the step in progress and end the turn cleanly.

Who changes what tomorrow

For any Claude Code user on a Max or Pro plan who has lost a window to a research run, the install is two commands. The mod is local, has no network calls, and refuses rather than crashes if a hook fails. The right test is to install it on the next planned fan-out session and read /agent-guard report afterwards to see which rules it tripped.

Source

rbartoli/agent-usage-guard on GitHub and its Show HN thread.