# Open-source Claude Code plugin holds agent spawns before they drain usage limits

published: 2026-10-24T11:05:52.954Z
topic: infrastructure
source: https://github.com/rbartoli/agent-usage-guard
url: https://aiagentnews.io/stories/open-source-claude-code-plugin-holds-agent-spawns-before-they-drain-usage-limits

agent-usage-guard is an MIT-licensed plugin for Claude Code that checks subagent fan-out, heavy-context prompts and retry loops before they run. It reads the plan's 5-hour and weekly usage percentages and asks the user in Claude Code's own dialog, or refuses when nobody can answer.

The plugin runs inside Claude Code and acts before an agent starts, a prompt is sent or a tool call runs. Its default limits cap agents running at once across every session on a machine at 4, agent starts or resumes at 12 per 10 minutes, and subagent tokens at 10 million per 10 minutes, with subagents barred from starting their own agents beyond one layer.

When a user is present, the guard asks in Claude Code's question dialog, and an approval holds until the condition clears or times out. In claude -p, the Agent SDK and dontAsk mode, where nobody can answer, it refuses and tells Claude why. From 95% of a plan window, each session is told to finish its current step and stop.

The guard makes no network requests and starts no processes, storing only counts and coarse buckets rather than prompt text or tool inputs. If one of its hooks fails, the event proceeds, except for an agent it cannot judge. The author reports that one research prompt at max effort once spawned 394 subagent calls and pushed 84M context tokens through the API in ten minutes.

## Why it matters if you build agents

Developers running Claude Code with subagents can set machine-wide caps on parallel agents, starts and context spend instead of hitting a lockout mid-task. The guard does not see everything, since teammates in separate terminal panes and tools the API runs itself are not holdable. Test the defaults against your own workload, because they are stricter than Claude Code's native caps.