What Stops Claude Code Burning Your Usage Window

One afternoon in June I gave Claude Code a research prompt at max effort. In ten minutes it made 394 subagent calls, 341 of them running at once, and pushed 84M tokens through the API. Then “Claude usage limit reached”, and I was 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 that holds agents, heavy context and retry loops before they spend the window. When I posted it on Reddit, the two top comments said Claude Code’s settings already cover it. I’d had the same doubt the day I started. My note from 24 July says: “I think we are recreating some of the things that Claude offers through settings, like compacting context automatically.”

Building is the fun part, so I don’t trust myself on this one. I went through everything I could find that claims to stop the burn: Claude Code’s own limits, the advice people give, and the plugins that turned up once Claude Code shipped mods. For each one I asked when it acts, and what it can actually hold.

The table

Approach	When it acts	What it holds
Claude Code’s limits	When an agent starts	The 21st running subagent in a session, and a 4th level of nesting. No cap on the total
Claude Code at the limit	At the limit	Nothing. The current step can finish, and the work carries on at reset
Instructions to the model	When the model listens	Nothing. A rule in CLAUDE.md, or the quota added to every prompt, is advice
Usage monitors	Never	Nothing. They show the number
Wind-down plugins	From 75–95% of the window	A note to finish the step and hand off. One also refuses new agents at 95%
Hard holds	From 90–95%, or when ahead of an even pace	Every tool call, until the reset or your OK
Subagent caps	When an agent starts	Agents past a count, per session. Some step agents down to a cheaper model
Recovery tools	After the limit	Nothing. They resume the work at reset
agent-usage-guard	Before an agent, a prompt or a tool call	Agents across every session on the machine, heavy context at any usage level, new agents from 80%

Auto mode came up too. It decides whether an action is safe to run without asking you. It never looks at your plan.

The crowded row is the monitors. Since 8 October I count more than 100 new repos on GitHub that show your Claude usage limits, at least 27 of them Claude Code mods.

What the table says

Most of it acts at the limit or after it. That’s worth something. Work stops at a clean point instead of mid-edit, with a handoff to pick up later. But the window is a budget, and at 90% it’s already spent. If ten agents burned 80% of it in twenty minutes, a note at 90% saves the last tenth.

Most of the rest is advice. A rule in CLAUDE.md, the quota in every prompt and a note to wrap up all rely on the model listening. By default it can’t even see how much of your plan is left. I’d rather have a rule it can’t argue with.

Almost all of it counts per session. Claude Code lets each session run 20 subagents at once. Before a typical lockout of mine, a dozen sessions had been running, so the native limit would have allowed 240. Of the tools I read, mine is the only one that counts agents across sessions.

My row, measured

Mine asks in Claude Code’s own question dialog, and refuses with a reason when nobody can answer. The numbers come from my Claude Code transcripts and the guard’s own journal.

The first version was plain hooks, and I ran it for 75 days. My largest agent burst fell from 365 starts in ten minutes to 27, and main-conversation requests at 500k+ context from 14.5% to 0.6%. Lockouts went up, from one a week to almost two. They came from many main sessions running in parallel, which no rule of mine held.

The mod replaced the hooks on 7 October. In the 15 days since, the 5-hour limit has locked me out six times and the weekly limit once. The first came from sessions started before the switch, which didn’t run the mod. Before each of the other five, 7 to 16 sessions had been running in the previous five hours. In two of them, subagents had done most of the work, and the guard had asked me 8 and 23 times whether to let more agents start or a long heavy turn carry on. I said yes every time.

I take any answer that saves tokens without stopping the work. Asked whether to compact a heavy session before sending, I compacted 47 times out of 50. Asked whether a long turn past 400k should keep going, I said yes 39 times out of 47, and the other 8 compacted after the turn. I almost never chose to stop. The hooks refused to work past 500k until I compacted. Since the switch, 6% of my main requests have run past 500k, against 0.6% under the hooks.

So the guard asks at the right moments, and I keep the work going. Its plan-window rules also hold only new agents, so a dozen main sessions can still run the window to zero. Next is a note at 95% that tells every session to finish its step and start nothing big. The wind-down plugins had that idea first.

What I’d do

Set the native limits first. They’re free and need nothing installed:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "1",
    "CLAUDE_CODE_SUBAGENT_MODEL": "sonnet",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

The first stops subagents starting their own. The other two run every subagent on Sonnet, whatever model Claude asks for. Skip them if your subagents need your main model.

Then match the tool to what burns your window. If it’s fan-out and heavy sessions, hold them before the spend, which is what my guard is for. If it’s many sessions running it down together, the only rows that hold main sessions are the hard holds, and they hold every tool call.

Try it

Free, MIT, and it makes no network calls. In Claude Code 2.1.287 or later:

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

The code, the defaults and what it can’t see: github.com/rbartoli/agent-usage-guard.