A free, MIT-licensed Claude Code plugin that pauses subagent fan-out, heavy-context prompts and retry loops before they burn a usage window.
agent-usage-guard product gallery image 1
1 / 3Overview
What is agent-usage-guard?
Stop Claude Code from spending your usage window in minutes
What is agent-usage-guard?
Agent-usage-guard is a Claude Code mod that stops Claude Code from spending a usage window in minutes. It was built after one prompt spawned 394 agent calls and replayed 84M tokens of context in ten minutes, and after 12 session-limit lockouts in 60 days.
Highlights
- Plan-aware gates: reads the live 5-hour and weekly usage percentages, asks before new agents once a window reaches 80%, and refuses at 95%.
- Fan-out limits: asks when too many agents start at once or too many start within 10 minutes, counting across every session on the machine.
- Heavy-context gates: asks before a prompt resends 500k or more tokens of context, suggesting compact-then-send first.
- Retry-loop protection: refuses after 3 identical failures, and pauses agent spawns after 5 refused calls within 10 minutes.
- Local and privacy-minimal: no network calls, no processes, and it never stores prompt text; it stores only counts and coarse buckets.
- Fails open: if a hook fails, the event goes ahead, so a broken guard never breaks a session.
- Reporting: /agent-guard report shows what it did, and /agent-guard status shows what it sees right now.
Pricing
Free. MIT-licensed, installed with one plugin install command inside Claude Code 2.1.287 or later.
Platforms and languages
agent-usage-guard Availability
Platforms
Languages
Capabilities
agent-usage-guard Key Features
Subagent fan-out guard
Asks before subagents fan out once a plan window reaches 80%, or when too many agents start at once, and refuses when nobody can answer.
Heavy-context prompt guard
Asks before a prompt resends 500k or more tokens of context, so you can compact first and then send.
Retry-loop guard
Refuses a retry loop after 3 identical failures, instead of letting it run round again.
Machine-wide agent counting
Counts agents across every Claude Code session on the machine, with caps on concurrent agents, starts per 10 minutes and subagent tokens.
Local and privacy-minimal
Runs locally with no network calls and never stores prompt text; if it breaks, it fails open so it never breaks a session.
Usage report
/agent-guard report shows everything the guard did, including questions, refusals and lockouts it did not prevent.
Best for
Who uses agent-usage-guard?
Claude Code users on subscription plans who run many agents or large contexts
Stop one prompt from spawning hundreds of agents or replaying tens of millions of context tokens in minutes
Plans and access
agent-usage-guard Pricing
Free
Free MIT-licensed Claude Code plugin
Common questions
agent-usage-guard FAQs
What is agent-usage-guard?
A Claude Code mod that holds runaway agent spend before it happens: it reads your plan's live 5-hour and weekly usage, then asks before subagent fan-out, heavy-context prompts and retry loops.
How do I install it?
Inside Claude Code version 2.1.287 or later, run /plugin marketplace add rbartoli/agent-usage-guard, then /plugin install agent-usage-guard@agent-usage-guard.
What happens if nobody can answer its question?
It refuses, and tells Claude why, so the model can wait, batch the work, or stop. In unattended modes such as claude -p, gates refuse instead of asking.
Does it send my prompts anywhere?
No. It makes no network calls, starts no processes, and never stores prompt text, tool inputs or model output.
What if the guard itself breaks?
It fails open: a broken guard never breaks your session, and the one exception is an agent it could not judge, which is refused so Claude starts it again.
Reviews
See what the community thinks and share your experience.
—
Based on 0 ratings
Rating distribution
Community reviews
No reviews
No written reviews yet.
