Skip to content
claudemods

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-guard
All install options ↓

What 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. 1.One line, inside Claude Code

    /plugin install agent-usage-guard --marketplace rbartoli/agent-usage-guard

    Paste into a running session (v2.1.275+). Claude Code asks to add the marketplace first.

  2. 2.From your shell

    claude plugin marketplace add rbartoli/agent-usage-guard
    claude plugin install agent-usage-guard@agent-usage-guard

    Then run /reload-plugins in any session that is already open.

  3. 3.Try it without installing

    git clone https://github.com/rbartoli/agent-usage-guard
    claude --plugin-dir ./agent-usage-guard

    Loads 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.read reads only its own plugin.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_GUARD is not set to 0, false, off or no.
  • 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 resume to let it ask again.
  • Subagents that Claude Code starts without a spawn event (such as /subtask forks) 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.
Usage Meter running in Claude CodeFeatured

Usage 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

Agent Radar running in Claude CodeFeatured

Agent 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

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.