agent-usage-guard

About

Usage limits for Claude Code agents

The author built it after one max-effort research prompt spawned 394 subagent calls and hit the usage limit in ten minutes. By default new agents need approval once a plan window is 80% full and are refused at 95%, no more than 4 agents run at once across the machine, subagents cannot start their own agents, and the same failing tool call is refused after 3 identical failures. Prompts that would re-read 500k tokens of context ask first (compact then send, send anyway, or cancel). An approval lifts its condition for a while, so the same question does not repeat every call. When nobody can answer, as in claude -p or the Agent SDK, it refuses and tells Claude why so the model can wait, batch or stop. /agent-guard report shows what it held and what you answered. It makes no network requests, starts no processes, and stores only counts and coarse buckets, never prompt text or tool inputs. Every threshold is an environment variable. The repo is MIT with 57 GitHub stars and was a Show HN on 2026-10-22.

Features

• Reads the 5-hour and weekly plan percentages Claude Code reports
• Machine-wide caps on parallel agents, agent starts and subagent tokens
• Asks before heavy-context prompts and tool loops
• Refuses identical retries after repeated failures
• /agent-guard report of every question and refusal
• No network, no processes, no prompt text stored

Install