agent-usage-guard plugin
Claude Code mod that holds subagent fan-out, heavy context and retry loops before they eat your usage window.
- 97 ★ on the repository
- Last commit
- MIT
Minimal access
Why this level
- The mod can refuse agent launches and tool calls when a usage window is nearly full.
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/agent-usage-guardDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewMinimal accessThe tool runs nothing and makes no network calls.
- The mod can refuse agent launches and tool calls when a usage window is nearly full.
This is third-party code. Review the repository files before installing.
What it does
agent-usage-guard reads your plan usage and acts before the spend: before an agent starts, a prompt is sent or a tool call runs. Agent limits hold across every Claude Code session on the machine. When you are at the keyboard the mod asks through the native Claude Code question dialog. When nobody can answer, it refuses and tells the model why, so the model can wait, batch the work or stop. By default new agents need approval once a window is 80 percent full and are refused at 95. One approval holds until the condition changes, so the same question does not return on every call. The `/agent-guard report` command shows what the mod did.
Who it is for. People who run parallel subagents and keep hitting the Claude Code five-hour or weekly usage window.
Good fit when
- A research prompt at max effort spawns hundreds of subagents within minutes.
- A long session resumes after a couple of hours and the first send would rewrite an expired cache of hundreds of thousands of tokens.
- A night retry loop or schedule burns the limit while you sleep.
- You need a report on where and how the guard acted.
Not a fit when
- You have no subscription and the usage window does not affect you.
- You need spend statistics by project, while the mod stores only counts and coarse buckets.
- Your Claude Code is older than 2.1.287.
Example request
Show what agent-usage-guard sees and simulate the question it asks when too many agents run in parallel.Limitations
The mod needs Claude Code 2.1.287 or newer with mods enabled, which is the default. It reads the 5-hour and weekly percentages that Claude Code reports, so protection accuracy depends on this data. When one of its hooks fails, the event goes ahead so a broken guard never breaks the session. The exception is an agent the mod could not judge: it is refused and Claude starts it again. The mod is local, with no network and no processes, and stores counts and never prompt text or model output.
How to disable. Run `/plugin uninstall agent-usage-guard@agent-usage-guard` or switch mods off in Claude Code settings. Saved counters live in the mod data directory.
FAQ
How do I check the mod works?
Run `/agent-guard` to see what the mod sees. `/agent-guard simulate concurrency` shows the too-many-agents question with nothing held or spent.
What does the mod do at 95 percent of a window?
It refuses new agents, refuses `ScheduleWakeup` and `CronCreate` and asks each session once to finish its step and say what is left.
Does the mod send data over the network?
No. It runs locally with no network and no processes and stores only counts and coarse buckets without prompt text.
Can it break my session?
No, when a hook fails the event goes ahead. One exception: an agent the mod could not judge is refused and Claude starts it again.
How do I turn mods off?
The off settings are listed in the Claude Code mods overview. The mod itself is removed with `/plugin uninstall`.
Discussion
No questions or reviews yet.
Related
PluginsClaude Code kit with eight phase agents, 21 skills and hooks that keep the agent inside set limits.
A ready-made Claude Code setup: agents, slash commands, skills, safety hooks, rules and MCP connections in one install
agentplay turns local Claude Code, Codex and Cursor sessions into a file map and a replayable step timeline.
Three Claude Code plugins: the savvy-flow orchestrator with tiered subagents and two mods for a progress panel and a cache timer
A Claude Code and Codex plugin that finds task code by symbols and Git history, builds context and picks a specialist role.
A Claude Code plugin with seven specialized subagents and approval gates: the agent proposes a plan and waits for confirmation before touching code
README in short
The mod keeps usage under control through rules: plan windows, growth speed, agent count and context weight. The author cites 60 days of logs with 12 usage lockouts as the reason for building it.