agent-usage-guard
Holds a burst of subagents, a huge prompt or a retry loop before it eats your plan window.
Recorded by ClaudeMods · By Riccardo Bartoli · Updated Oct 23, 2026
What agent-usage-guard looks like in use
Before you install
A mod is not sandboxed. It runs inside Claude Code with your permissions. This one:
- can read Claude settings
- can read Every prompt you send
- can read Every tool call
Check it yourself before running it: git clone https://github.com/rbartoli/agent-usage-guard && claude plugin validate ./ · MIT licensed
Install
claude plugin marketplace add rbartoli/agent-usage-guard
claude plugin install agent-usage-guard@agent-usage-guard
Then run /agent-guard inside the session.
Needs Claude Code 2.1.287 or later. After installing, run
/reload-plugins if the session was already open.
Full install guide
Why this exists
The author built it after one max-effort research prompt fanned out into 394 subagent calls, 341 of them at once, and pushed 84 million context tokens through the API in ten minutes. The result was a lockout until the window reset.
That is not a model failure. It is a fan-out nobody was watching.
What it actually holds back
Three patterns, each with a default you can change:
A burst of agents. More than 4 running at once, 12 started or resumed in 10 minutes, or 10 million tokens processed by subagents in 10 minutes. It counts across every Claude Code session on the machine, not just the one you are looking at.
A prompt that re-reads a huge context. One that would re-read 500k tokens. You choose compact then send, send anyway, or cancel.
A tool loop. The 21st tool call within 10 minutes while the conversation or agent making it carries 400k tokens.
It also refuses on its own, without asking: new agents once a plan window reaches 95%, a subagent starting agents of its own (one layer below the main conversation is the default), and the same tool call after three identical failures with no other call in between.
The detail that makes it usable
An approval holds, so the same question does not come back on every call — a plan window until it resets, a heavy context until it shrinks, agent counts for 10 minutes. Declining tells Claude to start no agents for 10 minutes and you are not asked again in that window.
Words you type in the dialog reach Claude, so an answer like “use haiku agents instead” works.
When to skip it
If you never run subagents, this is weight for nothing. It watches fan-out; with a single conversation there is no fan-out to watch.
And if you work in claude -p, the Agent SDK or the dontAsk permission mode, every question becomes a refusal — the guard has nobody to ask. That is by design, but it means the guard behaves as a hard cap there, not as a prompt.
Similar mods
context-inspector
Finds repeated reads, similar outputs and compaction-related waste.
cache-tax
Keeps the prompt cache warm during breaks and stops a cold send once — with its price.
cache-keeper
Combines cache timing, cold-send warnings, chat board and handoff.
idle-compact
Compacts once after fifty idle minutes, before cache expiry.
Popular mods
agent-profiler
Breaks a session into model wait, tool and subagent time.
Agent Time Machine
Records tool calls and project snapshots on a branching timeline.
loop-detective
Collects evidence when the same Bash failure keeps repeating.
pin-memo
Keeps personal notes and todos above the prompt across resumes.