Agent Usage Guard: a Claude Code mod that protects your Claude Code usage limit
Holds subagent fan-out, heavy-context prompts and retry loops before they burn through your Claude Code plan window.
Permissions
- Reads filesCan read files and list directories on your machine ($.fs.read / list / stat / exists).
- Intercepts tool callsSees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Reads your promptsCan see what you type and the conversation transcript (prompt.* / session.append / session.messages).
- Changes the UIDraws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
- Adds commands/toolsRegisters new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
- Stores dataKeeps data between sessions in the plugin's private store ($.store.*).
- tested with
- v2.1.310
- last tested
- requires
- Claude Code ≥ 2.1.287
- surfaces
- status
Install inside Claude Code:
/plugin install agent-usage-guard --marketplace rbartoli/agent-usage-guardWhat does this mod do?
Agent Usage Guard is a community mod by Riccardo Bartoli (rbartoli). It aims to keep one runaway session from using up your Claude Code usage limit in a few minutes. It acts before the spend: before a subagent starts, before a prompt is sent, and before a tool call runs.
The rules, with the defaults from the author's README:
- Plan windows: new agents need your approval once the 5-hour or weekly window is 80% full, and are refused at 95%. At 95% each session is also told once to finish its step and say what is left.
- Agents: at most 4 running at once and 12 started or resumed per 10 minutes, counted across every Claude Code session on the machine, plus a 10M subagent-token budget per window. Subagents may not start agents of their own.
- Context: Claude is told once to keep the turn bounded at 300k tokens. A prompt that would re-read 500k tokens asks first (compact then send, send anyway, or cancel). After 20 tool calls in 10 minutes at 400k context, it asks before the next.
- Loops: the same tool call failing three times in a row is refused, and five refused agent calls pause spawns for 10 minutes.
/agent-guard report summarizes what it did over the last days, including usage-limit lockouts it did not prevent.
Install
Use any of the methods in the install block; they install straight from the author's own marketplace. Then run /agent-guard to see what the guard sees. The mod is on by default once installed.
$ install agent-usage-guard
Requires Claude Code ≥ 2.1.287
Installs from the author's own marketplace: rbartoli/agent-usage-guard
1.One line, inside Claude Code
/plugin install agent-usage-guard --marketplace rbartoli/agent-usage-guardPaste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.
2.From your shell
claude plugin marketplace add rbartoli/agent-usage-guard claude plugin install agent-usage-guard@agent-usage-guardThen run /reload-plugins in any session that is already open.
3.Try it without installing
git clone https://github.com/rbartoli/agent-usage-guard claude --plugin-dir ./agent-usage-guardLoads the mod for one session only. Nothing is added to your settings.
How it works
The hooks module is hooks/register.ts, an adapter over a core/ folder of pure functions that perform no I/O. The adapter turns Claude Code events into facts, asks the questions, and keeps per-session counts in the mod store so other sessions can read them. The agent hook, from hooks/register.ts:
on('agent.spawn', async ($, e, next) => {
if (!config.enabled) return next(e)
// ...
const { verdict, reservedAt } = await agentVerdict($, now, request)
if (verdict.kind === 'deny') {
await journalDenial($, verdict, 'Agent')
return { deny: verdict.message }
}
// ... start the agent and count it
}).catch(($, e, next) =>
next.called
? failOpen($, 'agent.spawn', next.error, () => next(e))
: { deny: `agent-usage-guard could not judge this agent ... Start it again.` },
)Most hooks fail open: if one throws, the event goes ahead. The one exception is an agent the guard could not judge, which is refused so Claude starts it again. Each session publishes its running-agent count to the store on a one-minute heartbeat, which is how the limits hold across sessions. A published record that nobody refreshed for 15 minutes stops counting.
Customize it
Everything is set with environment variables, in your shell or under env in ~/.claude/settings.json. AGENT_GUARD switches the guard on or off, AGENT_GUARD_AGENT_MAX, AGENT_GUARD_ROLLING_MAX and AGENT_GUARD_AGENT_TOKENS_MAX set the agent limits, AGENT_GUARD_LIMIT_ASK_PERCENT and AGENT_GUARD_LIMIT_DENY_PERCENT set the plan-window thresholds, and AGENT_GUARD_CONTEXT_WARN and AGENT_GUARD_CONTEXT_HARD set the context thresholds. AGENT_GUARD_JOURNAL=0 stops the journal. A value that is not a number in range keeps its default, and /agent-guard says so. The in-session commands are /agent-guard status, allow, pause, resume, report and help.
Permissions & safety
We read every file the plugin can execute before running it: hooks/hooks.json, hooks/register.ts and the 13 files in core/ (about 72 KB). There is no package.json, no dependencies, no bundled or minified code and no binary; the plugin icon is the only non-text file in the plugin folder. The demo/ folder, which builds the author's GIF, is not loaded by the plugin and we did not run it. Here is what we found:
- Gates calls: this is a gating mod. It can deny agent starts and tool calls, and it can drop a prompt before it is sent. That matches the README. It asks you first whenever you can answer.
- Sends a prompt: after you choose "Compact, then send", it compacts the session and submits your own prompt unchanged with
$.prompt.submit. If compaction fails, your prompt goes back into the input box. - Adds text for Claude: the prompt hook can append a short note (context passed 300k, or a plan window reached 95%). It is plain text built from the code, with no hidden or zero-width characters.
- Writes files: only through the mod store (
$.store), a JSON file under~/.claude/plugins/store/. It writes no settings and no shell files, and it creates no daemons.$.fs.readreads only its ownplugin.json. - Reads environment variables: only the 22
AGENT_GUARD*variables listed by validate. It does not read credentials. - No network, no processes, no telemetry.
claude plugin validate reported no errors or warnings. It lists 11 gating hooks, all with a .catch. The author's test suite passed on Claude Code 2.1.310: 103 pass, 0 fail. The license is MIT, with a LICENSE file.
- Reads files
- Can read files and list directories on your machine ($.fs.read / list / stat / exists).
- Intercepts tool calls
- Sees every tool call Claude makes (tool.call / tool.check) and could block or change it.
- Reads your prompts
- Can see what you type and the conversation transcript (prompt.* / session.append / session.messages).
- Changes the UI
- Draws into the Claude Code interface: bands, panes, status text, toasts (ui.render / $.ui.*).
- Adds commands/tools
- Registers new slash commands or tools that you or Claude can invoke ($.command.register / $.tool.register).
- Stores data
- Keeps data between sessions in the plugin's private store ($.store.*).
Compatibility & troubleshooting
Checked with Claude Code 2.1.310 on macOS (validate and the author's tests). The README asks for Claude Code 2.1.287 or later. Mods do not run in a Desktop-app WSL session. If the guard seems silent:
- Run
/agent-guard status. It shows the version that is loaded and any setting it ignored. - Check that
AGENT_GUARDis not set to0,false,offorno. - On an API key, plan-window rules have nothing to read; only the count and token budgets apply.
- If you answered "no" to a question, new agents are refused for 10 minutes. Run
/agent-guard resumeto let it ask again. - Subagents that Claude Code starts without a spawn event (such as
/subtaskforks) are counted but never held.
FAQ
- Does Agent Usage Guard send anything over the network?
- No. The hooks module calls no network API and starts no processes. The only file it reads is its own plugin.json, to show its version in /agent-guard status. Its state lives in the mod store under ~/.claude/plugins/store/.
- What happens when it holds an agent or a prompt?
- When you can answer, it asks in Claude Code's own question dialog. When nobody can (claude -p, the Agent SDK, dontAsk mode), it refuses and tells Claude why, so the model can wait, batch the work or stop. Dismissing a question counts as no, never as yes.
- How do I turn it off or lift a limit?
- Set AGENT_GUARD=0 to turn it off without uninstalling. To lift limits for a while, type /agent-guard allow [agents|context] [minutes]. The guard refuses that command when another plugin runs it, so only you can lift limits.
- Does it work with an API key instead of a subscription?
- Partly. API-key sessions report no plan-window percentages, so only the token and count budgets (agents at once, starts per window, subagent tokens, context size) apply. The README also suggests AGENT_GUARD_DORMANT_SECONDS=300 there, because the prompt cache lasts five minutes.
- What does it store about my prompts?
- Counts and coarse buckets only. According to the README and the code we read, journal rows hold the time, a session-id prefix, the rule, the tool name, a context bucket such as 400-500k, the plan window and your answer. A tool call is reduced to a 13-character fingerprint; prompt text and tool inputs are not stored.
# Related mods
FeaturedUsage Meter
Your plan's 5-hour and 7-day usage as small bars above the Claude Code prompt, with reset countdown and session cost.
- above-prompt
- toast
- Changes the UI
tested with v2.1.291
FeaturedAgent Radar
One live line above the prompt per running subagent: time, tool count and what it is doing now, plus a /radar pane.
- above-prompt
- pane
- toast
- Intercepts tool calls
- Reads your prompts
- Changes the UI
- Adds commands/tools
tested with v2.1.291
Loop Detective
Opens a case when the same Bash command fails the same way three times in a row, and shows it in the status line.
- status
- toast
- pane
- Intercepts tool calls
- Changes the UI
- Adds commands/tools
tested with v2.1.303
More in Safety guards, Context, quota, cost.