Repolode
Submit
rbartoli

rbartoli/agent-usage-guard

A Claude Code mod that holds subagent fan-out, heavy-context prompts and retry loops before they consume your plan's usage window.

View on GitHub
Stars
94
Forks
5
Open issues
0
Last commit
yesterday

What is it?

agent-usage-guard is a mod for Claude Code that checks each agent start, prompt and tool call before it runs. It reads the 5-hour and weekly usage percentages reported for your plan, and counts running and recent agents across every Claude Code session on the machine. When a limit is reached, it asks in Claude Code's own question dialog, or refuses and explains the reason when no one can answer, as in claude -p or the Agent SDK.

Its default rules cap concurrent agents at four, limit starts to twelve per ten minutes and subagent tokens to ten million per window, and flag large contexts such as prompts that would re-read 500k tokens or tool-call bursts at high context. An approval stays in effect until the condition clears or times out, so the same question is not repeated on every call. The guard fails open: if one of its hooks errors, the event proceeds.

It runs locally with no network access or background processes. It stores counts and coarse buckets rather than prompt text, tool inputs or model output, and the /agent-guard report command summarizes what it intervened on.

Key features

  • 01Asks before new agents start once the plan's 5-hour or weekly window passes set thresholds.
  • 02Caps concurrent agents, agent starts and subagent tokens across all sessions on the machine.
  • 03Asks before prompts that would re-read large contexts, and limits tool-call bursts at high context.
  • 04Refuses identical tool retries after repeated failures.
  • 05Runs locally with no network access and stores no prompt or tool content.
  • 06/agent-guard report summarizes the interventions made.

Use cases

  • Running parallel research or multi-agent workflows in Claude Code without exhausting the five-hour usage window.
  • Scripting claude -p or Agent SDK jobs that should refuse heavy agent fan-out instead of hitting a lockout.
  • Preventing a looping retry from burning context on a long-running session.

Quick start

  1. 1

    Add the marketplace inside Claude Code

    /plugin marketplace add rbartoli/agent-usage-guard
  2. 2

    Install the plugin

    /plugin install agent-usage-guard@agent-usage-guard
  3. 3

    Reload plugins

    /reload-plugins
  4. 4

    Run the status command to see what the guard sees

    /agent-guard

Things to know

  • Requires Claude Code v2.1.287 or later.
  • Some paths are not covered, such as /subtask forks and teammates running in their own terminal panes.
  • Plan-window readings are unavailable for API-key sessions.
  • Does not run in a Desktop-app WSL session.

In collections

Claude Code tools, skills & pluginsOpen-source AI agent frameworks & apps

Topics

#ai-agents#claude-code#rate-limiting#guardrails#subagents#developer-tools#claude-code-mod#claude-code-plugin#typescript#usage-limits

FAQ

What is agent-usage-guard?
A Claude Code mod that holds subagent fan-out, heavy-context prompts and retry loops before they consume your plan's usage window. agent-usage-guard is a mod for Claude Code that checks each agent start, prompt and tool call before it runs. It reads the 5-hour and weekly usage percentages reported for your plan, and counts running and recent agents across every Claude Code session on the machine. When a limit is reached, it asks in Claude Code's own question dialog, or refuses and explains the reason when no one can answer, as in claude -p or the Agent SDK.
Is agent-usage-guard free to use? What license does it have?
agent-usage-guard is open source under the MIT license. Check the license terms before using it in commercial products.
Is agent-usage-guard still maintained?
Actively maintained. The last commit to agent-usage-guard was on Nov 6, 2026.
What can I use agent-usage-guard for?
Running parallel research or multi-agent workflows in Claude Code without exhausting the five-hour usage window. Scripting claude -p or Agent SDK jobs that should refuse heavy agent fan-out instead of hitting a lockout. Preventing a looping retry from burning context on a long-running session.
How do I install agent-usage-guard?
Add the marketplace inside Claude Code: /plugin marketplace add rbartoli/agent-usage-guard Install the plugin: /plugin install agent-usage-guard@agent-usage-guard Reload plugins: /reload-plugins Run the status command to see what the guard sees: /agent-guard
Where can I get agent-usage-guard?
The source code and installation instructions are on GitHub: https://github.com/rbartoli/agent-usage-guard

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects