agent-usage-guard is a Claude Code mod that acts before spend happens. It reads your plan's live usage and holds subagent fan-out, heavy-context prompts and retry loops before an agent starts, a prompt is sent, or a tool call runs. Agent limits apply across every Claude Code session on your machine, and fan-out and heavy context are capped at any usage level, not only near the limit.
When you are at the keyboard, the guard asks you in Claude Code's own question dialog. When nobody can answer, it refuses and tells Claude why, so the model can wait, batch the work, or stop. The 5-hour and weekly percentages Claude Code reports drive its plan-aware limits, and an approval lifts its condition until the window resets or times out, so the same question does not repeat call after call.
The project was built after a single research prompt at max effort spawned 394 subagent calls, with 341 running at once, and pushed 84M context tokens through the API in ten minutes, triggering a lockout. The author's own logs held 12 lockouts over 60 days. Each protection removes one factor in that failure pattern.
The guard is local and privacy-minimal. It makes no network calls, stores only counts and coarse buckets, and never keeps prompt text, tool inputs or model output. It fails open, so a broken hook never breaks a session. The one exception is an agent it could not judge in time, which is refused so Claude can start it again. Install it inside Claude Code v2.1.287 or later, then run /agent-guard to see what it sees.
Source: Hacker News · Summarized by HeadlinesBriefing