What is agent-usage-guard?
agent-usage-guard is a Claude Code mod that checks plan usage and puts limits on agent activity, large-context work, and repeated failures before they consume more of a usage window. It is for people using Claude Code who want to keep long or parallel sessions from exhausting their five-hour or weekly allowance unexpectedly. The mod runs locally across Claude Code sessions on the machine and asks for approval in Claude Code when a rule is reached.
agent-usage-guard Features:
Plan Usage Checks: The mod reads the five-hour and weekly usage percentages reported by Claude Code and applies rules as those windows fill or usage rises quickly.
Agent Limits: It can ask before agent activity exceeds configured limits for concurrent agents, starts within ten minutes, or subagent tokens processed.
Context Safeguards: It can flag prompts that would reread a large amount of context, heavy tool-call loops, and dormant sessions whose prompt cache may have expired.
Retry Controls: After three identical tool-call failures in a row, it refuses the same retry, and repeated refused agent calls can pause new agent starts.
Approval Dialogs: When a user can respond, the mod holds the action for a decision in Claude Code's question dialog and can keep an approval active for a set period or condition.
Status and Reports: The status display shows current agent counts and recent holds or refusals, while the report command summarizes what the mod did on the machine.
agent-usage-guard Benefits:
Fewer Lockouts: Early checks can help users keep work within a usage window instead of discovering that a session has reached its limit after a burst of activity.
Clearer Decisions: Approval prompts explain when a limit is being reached, giving users a chance to allow, stop, or change the work before it proceeds.
Less Repeat Friction: An approval can cover a condition until it clears or times out, reducing repeated questions while the same situation continues.
Private Local Use: Because it runs without network access and does not store prompt text, tool inputs, or model output, usage checks do not require sharing that content with the mod.
Protected Sessions: If a hook fails, the event proceeds rather than leaving a broken guard to interrupt the Claude Code session.
Use Cases:
Parallel Agent Work: Use it while Claude Code runs research or coding tasks across several subagents, to review a proposed agent burst before it grows.
Long Conversations: Use it when continuing a large conversation after idle time, so a potentially expensive prompt-cache rewrite can be reviewed first.
High Usage Windows: Use it during a nearly full five-hour or weekly allowance to curb new agents and prompt Claude to finish its current step.
Automated Sessions: Use it with non-interactive Claude Code runs, where actions that meet a limit are refused with a reason rather than waiting for a user response.
Repeated Tool Errors: Use it when a tool keeps failing in the same way, to stop identical retries and let Claude choose another approach.

