rbartoli/agent-usage-guard

这是什么？

核心功能

• 01计划的 5 小时或每周用量超过阈值时，新代理启动前先询问。
• 02跨机器上所有会话统一限制同时运行的代理数、代理启动次数和子代理 token 总量。
• 03对会重新读取大上下文的提示先询问，并限制高上下文下的工具调用爆发。
• 04相同工具调用连续失败后，拒绝相同的重试。
• 05完全本地运行，不联网，不保存提示或工具内容。
• 06/agent-guard report 可查看所做的拦截记录。

适用场景

• 在 Claude Code 中运行并行研究或多代理工作流，同时避免耗尽 5 小时用量窗口。
• 在 claude -p 或 Agent SDK 脚本中，让过量的代理扇出被直接拒绝，而不是触发用量锁定。
• 防止长时间运行的会话因重复重试而持续消耗上下文。

快速上手

1. 1

   在 Claude Code 中添加插件市场

   /plugin marketplace add rbartoli/agent-usage-guard
2. 2

   安装插件

   /plugin install agent-usage-guard@agent-usage-guard
3. 3

   重新加载插件

   /reload-plugins
4. 4

   运行状态命令查看守卫当前状态

   /agent-guard

使用前须知

• !需要 Claude Code v2.1.287 或更高版本。
• !部分路径无法覆盖，例如 /subtask 分叉以及在独立终端窗格中运行的队友。
• !API 密钥会话无法获取套餐窗口用量数据。
• !不能在 Desktop 应用的 WSL 会话中运行。

收录于专题

标签

常见问题

agent-usage-guard 是什么？

Claude Code 插件，在子代理扇出、超大上下文提示和重试循环消耗用量窗口之前进行拦截和询问。 agent-usage-guard 是 Claude Code 的一个 mod，会在每次启动代理、发送提示或执行工具调用之前进行检查。它读取订阅计划报告的 5 小时和每周用量百分比，并统计同一台机器上所有 Claude Code 会话中正在运行和最近启动的代理数量。触发限制时，它会通过 Claude Code 自带的提问对话框询问用户；在 claude -p 或 Agent SDK 等无人应答的场景下，则直接拒绝并说明原因。

agent-usage-guard 可以免费使用吗？用的什么许可证？

agent-usage-guard 以 MIT 许可证开源。用于商业产品前，请先确认许可证条款。

agent-usage-guard 还在维护吗？

活跃维护中。agent-usage-guard 最近一次提交是在 2026年11月6日。

agent-usage-guard 适合用来做什么？

在 Claude Code 中运行并行研究或多代理工作流，同时避免耗尽 5 小时用量窗口。 在 claude -p 或 Agent SDK 脚本中，让过量的代理扇出被直接拒绝，而不是触发用量锁定。 防止长时间运行的会话因重复重试而持续消耗上下文。

agent-usage-guard 怎么安装和运行？

在 Claude Code 中添加插件市场: /plugin marketplace add rbartoli/agent-usage-guard 安装插件: /plugin install agent-usage-guard@agent-usage-guard 重新加载插件: /reload-plugins 运行状态命令查看守卫当前状态: /agent-guard

在哪里获取 agent-usage-guard？

源代码和安装说明在 GitHub 上：https://github.com/rbartoli/agent-usage-guard