停止Claude Code在十分钟内花费你的5小时使用窗口。
agent-usage-guard是Claude Code mod：它运行在Claude Code内部，并在事发前持有逃跑支出。 它读到你的计划的现场用法，它有副剂的扇形，沉重的文本churn和重试循环。
从Claude Code的交互式UI录制，加载了警卫。 一个脚本的本地API代表Claude，所以会话和符号计数被摆出，没有使用。 屏幕上每个问题都是警卫自己的从北星固定重建。
它在花费前行动，而不是在其之后：在agent开始前，发送一个提示，或者工具调用运行。 Agent限制在您的机器上每个Claude Code会话上都保持，扇形和重上下文在任何使用级别上都封顶，不仅接近极限。 当你在键盘上的时候，它问你，在 Claude Code 自己的问题对话框中。 当没有人能回答时，它拒绝并告诉Claude为什么，所以模型可以等待，批量工作，或者停止。 /agent护卫报告显示做了什么。
- 计划意识。 它阅读了5小时和每周百分比的Claude Code报告，并为您保留了窗口的结尾。
- 一个答案覆盖一段时间。 批准解除其状况，直到它澄清或时间结束，所以同样的问题不会在接到电话后再回电。
- 本地和隐私最小。 没有网络，没有进程。 它存储计数和粗糙的桶，从不提示文本，工具输入或模型输出。
- 失败了如果它的一个钩子失败了，事件就继续下去：一个断了的守卫永远不会打断你的会话。 其中一个例外是agent它不能及时判断，这被拒绝了，所以Claude重新开始。
在 Claude Code v2.1.287 或以后运行这些命令：
/plugin市场增加rbartoli/agent-usage-guard
/plugin 安装 agent- usage- guard@ agent- usage- guard
重装插件
然后运行/agent守护，看看它看到了什么。 模式默认在运行；概览列出了关闭它们的设置。
一天下午，我给Claude Code一个快速研究以最大努力。 它催生了394个子代理电话，其中341个同时运行，并在10分钟内通过API将84M上下文符号推向了它。 会议结束："达到Claude使用限制". 锁在窗子重设前
这不是一次性的。 60天我自己的日志举行了12次停机和166次 10分钟的windows与agent暴发。 故障模式乘法：大上下文×快速工具循环×平行agents×盲重试。 下面的每个保护都会消除一个因素。
不只是我：339个副剂来自一个单速率，半周的Max计划被递归产卵消耗，和多agent运行使用~15× 聊天会的符号。
Agents覆盖子代理，agent团队队友，工作流程agents，完成子代理与SendMessage恢复。 每个工具调用都是根据制作它的循环的上下文来判断的，所以一个小的副剂从不继承主对话的大小。
其问时。 这个问题出现在Claude Code自己的对话框中，Claude用来问你什么，而呼叫等待你的回答。 Agents在打开时平行地开始，它被挡住，Claude在回答后再次开始。 如果你允许的话，这个条件可以停留一段时间：一个计划窗口直到它重置，一个沉重的上下文直到它收缩(对于工具呼叫，最多一小时),agent计数10分钟。 如果拒绝或驳回问题，则Claude被告知在接下来的10分钟内不要开始agents(AGENT GUARD WINDOW SECONDS)，这时不再被询问。 输入的单词到达Claude，因此可以回答"使用haiku agents代替".
当无人能答。 在claude -p,Agent SDK和DontAsk模式中，agent或工具门拒绝而不是询问。 有原因时会发出强烈的呼声，一旦达到每10分钟1分钟的全机封顶，休眠的强烈呼声也会出现。 Claude将每次拒绝都视为工具的结果。 同一条件的重复拒绝每次措辞不同，并升级：第二次称无动于衷并尝试别的东西，第三次称结束转弯。 如果像/目标这样的停止钩继续重开转弯，用户必须决定拒绝称。
它留下的孤独。 它从来不持有背景任务的通知或另一会话的信息，因为这将失去结果。 它在使用限制后不再块提示：自v2.1.234起，Claude Code在限时等待，并在自行重置时继续(auto Continue AtUsageLimit). 警卫的工作是阻止你达到极限日记记录了它没有阻止的关机事件
警卫现在看到的情况
/agent-guard 允许 [agentsXXQQQQQQContext] [分钟] 取消本次会话的限制(默认：全部，10分钟)
/agent- 守护暂停 [分钟] 与允许的相同，每限
/agent-guard 恢复到一个允许的早期，解除 agent 暂停，并让拒绝的问题再次问
/agent-guard报告它在这台机器上的所作所为[日](默认：7天)
/agent守护符帮助这些命令
/agent-guard同时运行，即使是中转，也从未开始模型转弯，因此Claude从未看到过一个覆盘，不能将一个作为许可。 发送[allow-usage-guard]或[allow-agent-burst]单独作为提示，早期版本的标记与/agent-guard允许或允许agents相同。
对Claude Code v2.1.295进行了检查：
Mods运行于一个终端中的claude，在桌面应用的代码标签中，在claude -p和Agent SDK中。 它们不会在桌面应用的WSL会话中运行(Mods运行的地方).
土著界限仍然重要。 Claude Code在20个并行子剂(CLAUDE CODE MAX CONCURRENT SUBAGENTS)和三层筑巢(CLAUDE CODE MAX SUBAGENT SPAWN DEPTH)上封顶一个会话。 它对每期开始的agents总数没有限制。 警卫的缺省更严格，并跨过会话；本土的盖子仍然是警卫只计数的路径的外墙。
/agent-警卫报告30
报告计算了使用限制关闭(每一次锁定窗口)，计划窗口阈值交叉，以及你回答的每个问题和拒绝。 它读过每期的日记在这个机器上，从来没有离开它。 设定 AGENT GUARD JOURNAL=0停止录制。
一个mod在Claude Code内部运行，拥有权限；在安装一个之前读取一个mod能够达到什么。 这个是大约2400行的TypeScript没有依赖性，claude插件验证。 列出它调用的每一API和它读取的每一环境变量：
- 它不提出网络请求，也不开始任何进程。
- 它只决定上述规则所描述的内容：agent是否开始，发送一个提示，或者工具调用运行。 它随时会问你的答案，并在拒绝时给出理由。 它读取权限模式，但从未更改它们，它不会写设置。
- 它提交的唯一的提示是你自己的：在“完成后发送”之后，它会发出你输入的提示，没有改变，一旦压缩完成就会发出。
- 它的即时钩将您的即时钩传递在未变的提示上，新增是当上下文超过300k时Claude的一次性注释，或者持有先问的提示(当没有人能回答时，它就是称的原因). 它的SessionStart hook 改变不了什么。
- 它保持其状态在mod商店，JSON文件在~/.claude/plugins/store/下。 每个会话都会写自己的计数(运行 agents，最近的开始和休眠恢复，每分钟潜移符号，最新的5小时读数)，当它最后一次活动时( 保留30天，所以复会知道它闲置的时间)，以及它的日记行( 时间、 会话编号前缀、 规则、 工具名称、 上下文桶，如 400- 500k、 计划窗口和百分比、 拒绝号以及您的回答)。
它从不存储快速文本，工具输入，错误文本或模型输出。 一个工具呼叫被缩小为13个特征的指纹。 Agent名字留在记忆中，从未被写入。
- 90天以上的日刊日被删除(AGENT GURD JOURNAL DAYS)。
- 演示/ 构建上方的GIF，不是运行的一部分。 它从一个临时的家庭目录中开始Claude Code，上面有一个编成的 API 密钥用于一个脚本本地 API，并且没有读取您的证书。
设定 AGENT GUARD=0 将其关闭，而无需取消。
将这些变量设定为环境变量，或在 ~/.claude/settings.json 中位于嵌入层下。 时数以秒计；一个不在范围内的值保持其默认值，和/agent-guard 称 so.
休眠默认假设订阅在计划使用范围内获得的1小时即时缓存。 带有API密钥或额外使用，缓存持续5分钟，因此设置了AGENT GUARD DORMANT SECONDS=300.
规则生活在一个不执行I/O的牵引-不可知核(core/)中。 Claude Code Mod是它的首个适配器。 Docs/architecture.md描述的是适配器所保存的合同，以及agent机带必须提供什么来携带每个规则。
claude 插件验证。 -- trip
claude 插件测试
claude插件测试在Claude Code自己的测试包内运行套件：对核心进行单位测试，通过没有会话，模型或网络的钩子模块进行真实的Claude Code事件点火测试。 TESTING.MD覆盖了层层和每个测试证明的东西。
麻省理工学院
本文由 AI图鉴自动抓取并翻译，版权归原作者所有；如需查看原文请点下方链接。
Stops Claude Code from spending your five-hour usage window in ten minutes.
agent-usage-guard is a Claude Code mod: it runs inside Claude Code and holds runaway spend before it happens. It reads your plan's live usage, and it holds subagent fan-out, heavy-context churn and retry loops.
Recorded from Claude Code's interactive UI with the guard loaded. A scripted local API stands in for Claude, so the sessions and token counts are staged and no usage is spent. Every question on screen is the guard's own. Rebuild it from the Northstar fixture.
It acts before the spend, not after it: before an agent starts, a prompt is sent, or a tool call runs. Agent limits hold 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 it 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. /agent-guard report shows what it did.
- Plan-aware. It reads the 5-hour and weekly percentages Claude Code reports, and keeps the end of the window for you.
- One answer covers a while. An approval lifts its condition until it clears or times out, so the same question does not come back call after call.
- Local and privacy-minimal. No network, no processes. It stores counts and coarse buckets, never prompt text, tool inputs or model output.
- Fails open. If one of its hooks fails, the event goes ahead: a broken guard never breaks your session. The one exception is an agent it could not judge in time, which is refused so that Claude starts it again.
Run these commands inside Claude Code v2.1.287 or later:
/plugin marketplace add rbartoli/agent-usage-guard
/plugin install agent-usage-guard@agent-usage-guard
/reload-plugins
Then run /agent-guard to see what it sees. Mods are on by default; the overview lists the settings that turn them off.
One afternoon I gave Claude Code a research prompt at max effort. It spawned 394 subagent calls, 341 of them running at once, and pushed 84M context tokens through the API in ten minutes. Session over: "Claude usage limit reached." Locked out until the window reset.
That wasn't a one-off. Sixty days of my own logs held 12 lockouts and 166 ten-minute windows with agent bursts. The failure mode multiplies: a large context × rapid tool loops × parallel agents × blind retries. Each protection below removes one factor.
And it's not just me: 339 subagents from a single prompt, half a weekly Max plan consumed by recursive spawning, and multi-agent runs using ~15× the tokens of a chat session.
Agents covers subagents, agent-team teammates, workflow agents, and finished subagents resumed with SendMessage. Each tool call is judged on the context of the loop that makes it, so a small subagent never inherits the main conversation's size.
When it asks. The question appears in Claude Code's own dialog, the one Claude uses to ask you something, and the call waits for your answer. Agents started in parallel while it is open are held back, and Claude starts them again once you answer. If you allow it, that condition stays allowed for a while: a plan window until it resets, a heavy context until it shrinks (for tool calls, an hour at most), the agent counts for 10 minutes. If you decline or dismiss the question, Claude is told not to start agents for the next 10 minutes (AGENT_GUARD_WINDOW_SECONDS), and is not asked again in that time. Typed words reach Claude, so you can answer "use haiku agents instead".
When nobody can answer. In claude -p, the Agent SDK and dontAsk mode, an agent or tool gate refuses instead of asking. A heavy prompt is held with the reason, and so is a dormant heavy resume once the machine-wide cap of one per 10 minutes is reached. Claude reads each refusal as the tool's result. Repeat refusals of the same condition are worded differently each time and escalate: the second says nothing has changed and to try something else, the third says to end the turn. If a Stop hook such as /goal keeps reopening the turn, the refusal says the user has to decide.
What it leaves alone. It never holds a background task's notification or another session's message, because that would lose the result. It no longer blocks prompts after a usage limit: since v2.1.234, Claude Code waits at a limit and continues at reset on its own (autoContinueAtUsageLimit). The guard's job is to keep you from reaching the limit, and its journal counts the lockouts it did not prevent.
/agent-guard [status] what the guard sees right now
/agent-guard allow [agents|context] [minutes] lift its limits for this session (default: all, 10 min)
/agent-guard pause [minutes] the same as allow, for every limit
/agent-guard resume end an allow early, lift the agent pause, and let declined questions ask again
/agent-guard report [days] what it did on this machine (default: 7 days)
/agent-guard help these commands
/agent-guard runs at once, even mid-turn, and never starts a model turn, so Claude never sees an override and cannot take one as permission. Sending [allow-usage-guard] or [allow-agent-burst] alone as a prompt, the markers of earlier versions, does the same as /agent-guard allow or allow agents.
Checked against Claude Code v2.1.295:
Mods run in claude in a terminal, in the Desktop app's Code tab, in claude -p and the Agent SDK. They don't run in a Desktop-app WSL session (where mods run).
Native limits still matter. Claude Code caps a session at 20 concurrent subagents (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) and three layers of nesting (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). It has no limit on the total number of agents a session starts. The guard's defaults are stricter and span sessions; the native caps remain the outer wall for the paths the guard only counts.
/agent-guard report 30
The report counts usage-limit lockouts (each locked window once), plan-window threshold crossings, and every question and refusal by rule, with what you answered. It reads every session's journal on this machine and never leaves it. Set AGENT_GUARD_JOURNAL=0 to stop recording.
A mod runs inside Claude Code with your permissions; read what a mod can reach before you install one. This one is about 2,400 lines of TypeScript with no dependencies, and claude plugin validate . lists every API it calls and every environment variable it reads:
- It makes no network requests and starts no processes.
- It decides only what the rules above describe: whether an agent starts, a prompt is sent, or a tool call runs. It asks you whenever you can answer, and gives the reason when it refuses. It reads permission modes but never changes them, and it writes no settings.
- The only prompt it submits is your own: after "Compact, then send", it sends the prompt you typed, unchanged, once compaction finishes.
- Its prompt hook passes your prompt on unchanged, adds a one-time note for Claude when the context passes 300k, or holds the prompt to ask you first (when nobody can answer, it says why instead). Its SessionStart hook changes nothing.
- It keeps its state in the mod store, a JSON file under ~/.claude/plugins/store/. Each session writes its own counts (running agents, recent starts and dormant resumes, subagent tokens per minute, its latest 5-hour reading), when it was last active (kept 30 days, so a resumed session knows how long it sat idle), and its journal rows (time, a session-id prefix, rule, tool name, context bucket such as 400-500k, plan window and percentage, refusal number, and your answer).
- It never stores prompt text, tool inputs, error text or model output. A tool call is reduced to a 13-character fingerprint. Agent names stay in memory and are never written.
- Journal days older than 90 days are deleted (AGENT_GUARD_JOURNAL_DAYS).
- demo/, which builds the GIF above, is not part of what runs. It starts Claude Code in a temporary home directory with a made-up API key for a scripted local API, and reads none of your credentials.
Set AGENT_GUARD=0 to turn it off without uninstalling it.
Set these as environment variables, or under env in ~/.claude/settings.json. Times are in seconds; a value that isn't a number in range keeps its default, and /agent-guard says so.
The dormant default assumes the one-hour prompt cache that subscriptions get within plan usage. With an API key or extra usage, the cache lasts five minutes, so set AGENT_GUARD_DORMANT_SECONDS=300.
The rules live in a harness-agnostic core (core/) that performs no I/O. The Claude Code mod is its first adapter. docs/architecture.md describes the contract an adapter keeps and what another agent harness must offer to carry each rule.
claude plugin validate . --strict
claude plugin test
claude plugin test runs the suite inside Claude Code's own test kit: unit tests of the core, and tests that fire real Claude Code events through the hooks module with no session, model or network. TESTING.md covers the layers and what each test proves.
MIT
Auto-fetched and translated by AI Atlas. All rights belong to the original author.