agent-usage-guard is a Claude Code mod, licensed under MIT, that prevents sub-agent fan-out, heavy-context prompts, and looping retries before they exhaust your usage limit. It reads the percentages from Claude Code’s 5-hour and weekly windows, and counts agents across all open sessions on your machine. When a threshold is crossed, it asks you first; if no one answers, it refuses. Version 1.1.0, released October 23, 2026, adds a shutdown mode: when a plan window hits 95 percent, every session gets instructions to finish the current step and report what’s pending.
Update, October 24, 2026: at the time of publishing this note, the repository’s CHANGELOG lists two security fixes still marked as Unreleased. We explain them in the security section.
Why does Claude Code exhaust the usage limit so fast?
Because costs multiply, they don’t add. The author identifies four factors that amplify each other: large context, fast tool loops, parallel agents, and blind retries.
In the README, he recounts the afternoon that led him to build the guard. He gave Claude Code a research prompt with maximum effort, and Claude Code spawned 394 sub-agent calls, 341 of them simultaneously. In ten minutes it passed 84 million context tokens through the API and the session ended with the message Claude usage limit reached.
These are figures from the author himself, taken from his logs and not independently verified. According to the same account, across sixty days of logs he had 12 blocks. He also links similar public reports: 339 sub-agents from a single prompt, and half a weekly Max plan consumed by sub-agents that spawned other sub-agents.
Each guard rule eliminates one of those four factors.
What is a Claude Code mod?
A mod is a type of Claude Code plugin made up of JavaScript or TypeScript event handlers that run inside Claude Code. That’s the difference from classic hooks configured in settings.json, which run an external script. Because a mod lives in the same process, it can intervene in an event before it happens: hold a tool call while asking you a question, rewrite a prompt, or reject an action.
That’s exactly what agent-usage-guard needs. Its CHANGELOG explains that the previous version (0.2.5) was built on config hooks and could only approximate what mods expose directly: live context, plan window percentages, and an event that can be rejected before each agent starts.
Mods are active by default since Claude Code v2.1.287 in the terminal.
How does it limit Claude Code sub-agents and context?
The guard acts at three moments: before an agent starts, before a prompt is sent, and before a tool call executes. These are its default values according to the README:
| Area | Rule | Default | What it does |
|---|---|---|---|
| Plan window | Window this full | 80% | asks before new agents |
| Plan window | Window this full | 95% | rejects new agents |
| Plan window | 5-hour window rises this fast | 20 points / 10 min | asks |
| Agents | Agents running at once, across all sessions on the machine | 4 | asks |
| Agents | Agents started or resumed each 10 minutes | 12 | asks |
| Agents | Tokens processed by sub-agents each 10 minutes | 10M | asks |
| Agents | Sub-agents that spawn their own agents | depth 1 | rejects |
| Context | One-time notice for Claude to keep the turn short | 300k tokens | adds a note |
| Context | Prompt that would re-read this context | 500k tokens | asks: compact and send, send anyway, or cancel |
| Context | Tool calls each 10 min with this context | 20 calls at 400k | asks |
| Context | Heavy session inactive long enough for its cache to expire | 150k tokens, 1 h inactive | asks before rewriting cache |
| Loops | Same call fails over and over | 3 identical failures | rejects identical retry |
| Loops | Agents rejected in 10 minutes | 5 | pauses launches 10 min |
The inactive session rule has to do with prompt caching, which we explain in detail in Your 5-Minute Cache Doesn’t Last 5 Minutes. If you’re not using sub-agents yet, start with Sub-agents in Claude Code.
Two design decisions matter in daily use:
- One answer is good for a while. If you allow something, the guard doesn’t ask again until the condition disappears. A plan window stays allowed until it resets, and agent counts stay allowed for 10 minutes. The author built this in because his previous version asked 136 times in high-context sessions and the answer was “yes” 132 times.
- With no one there, it refuses. In
claude -p, the Agent SDK, ordontAskmode, it refuses and explains why. Claude reads the refusal as the tool result, so it can wait, batch the work, or stop. Repeated refusals escalate in tone, and the third one asks Claude to end the turn.
What does the new 95 percent shutdown mode do?
According to the 1.1.0 CHANGELOG, when any plan window on the machine hits 95 percent, the next prompt from every session gets a note for Claude: finish the current step, don’t start anything big, and close the turn with what’s done and what’s pending.
The author explains why he added it. The blocks he kept seeing after 1.0 came from many main sessions running in parallel, and no rule stopped those. Now when the block hits, he finds them at a clean point, not in the middle of a change. An inactive session also learns that another session filled the window. Each session gets the notice once, and only gets it again when the window drops below the threshold, like after its reset.
Version 1.1.1, released the same day, fixes a double count: since Claude Code 2.1.299, resuming a sub-agent with SendMessage counted as two starts. It also makes /agent-guard status show which version is running.
How do you install agent-usage-guard in Claude Code?
Inside Claude Code v2.1.287 or later, run:
/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins
Then run /agent-guard to see what the guard sees.
These are the commands you’ll use:
/agent-guard [status] what the guard sees right now
/agent-guard allow [agents|context] [minutes] lift its limits for this session (default: all, 10 min)
/agent-guard pause [minutes] the same as allow, for every limit
/agent-guard resume end an allow early
/agent-guard report [days] what it did on this machine (default: 7 days)
/agent-guard runs without starting a model turn, so Claude never sees an override and can’t take it as permission.
How do you adjust the thresholds?
With environment variables, or inside env in ~/.claude/settings.json. Some of the most useful:
AGENT_GUARD_AGENT_MAX: agents running at once on the machine (default4).AGENT_GUARD_LIMIT_ASK_PERCENTandAGENT_GUARD_LIMIT_DENY_PERCENT: thresholds for asking and refusing (80and95).AGENT_GUARD_CONTEXT_HARD: context above which a prompt asks before being sent (500000).AGENT_GUARD=0: turns off the guard without uninstalling it.
The README documents 22 variables in total.
Does it work with an API key?
Yes, with two differences. Sessions with an API key don’t report plan window percentages, so only token budgets and agent counts apply. Also, prompt caching lasts five minutes instead of one hour, so the README recommends AGENT_GUARD_DORMANT_SECONDS=300. The same goes if you use extra usage.
What can’t it see?
The README is explicit about its blind spots, verified against Claude Code v2.1.295:
- It doesn’t count sessions on other machines, because shared logs live in each machine’s mod store.
- It doesn’t see teammates running on their own terminal panel, because they run in other processes.
- Forks from
/subtask, and everything that starts without theagent.spawnevent, get counted but never held. - It doesn’t run in a WSL session from the desktop app.
Claude Code’s native limits still apply: a session can handle up to 20 concurrent sub-agents and three levels of nesting, but there’s no limit on the total number of agents a session can spawn. The guard’s defaults are stricter and cover all sessions.
Is it safe to install a Claude Code mod?
A mod runs with your permissions and isn’t sandboxed. Anthropic’s documentation says it plainly: a mod can read your files, environment variables, and session. According to the author’s privacy notes, the guard is about 2,400 lines of TypeScript with no dependencies, makes no network requests, doesn’t start processes, and stores counts and rough ranges—never prompt text or tool input. You can review which APIs it uses with claude plugin validate . before installing.
At the time of publishing this note, the CHANGELOG lists two fixes from a security review on October 24, 2026 that aren’t yet in a published version:
- Until that fix comes out, any other installed plugin could run
/agent-guard allowand lift all limits for up to eight hours. - A question that ended without an answer could let an agent start; with the fix it counts as “no”.
Before trusting the guard in sessions with other mods installed, check that your version includes both fixes. To review whether any mod is safe, see how we tested ModVet, the scanner that checks a plugin before you install it.
agent-usage-guard or Claude HUD?
They solve different problems and work well together. Claude HUD shows you what Claude Code is doing and how much it costs. agent-usage-guard puts a ceiling on that cost and enforces it before it’s spent.
What about you? How many sub-agents do you run in parallel in Claude Code before you start worrying about the limit?
- Several times a week
- Once in a while
- Never
- I’d rather pick something else (tell us what)
Comment below, or if you got this article by email, reply directly to the email: your reply gets published here.