headroom

你的编码 Agent 会在开始工作前检查 Claude 和 Codex 的限额。

headroomd 会读取订阅显示的 5 小时和每周限额，并通过命令行或 MCP 给出继续、等待或改道的建议。

npm install -g headroomd   # or: brew install apertur3/tap/headroom
headroom setup
headroom can claude-fable --owner me && echo go

然后安装 Claude Code 插件（需要先安装上面的 headroomd）：

claude plugin marketplace add Apertur3/headroom
claude plugin install headroom@headroom

支持 macOS、Linux、Windows（实验性）。无遥测。零运行时依赖。

与 headroomlabs-ai/headroom（上下文压缩项目）无关。

安装

需要 Node 22.13 或更高版本。npm 包为 headroomd；Homebrew formula 为 apertur3/tap/headroom。两者都会安装 headroom 命令。

npm install -g headroomd
# or, on macOS and Linux: brew install apertur3/tap/headroom
# finds your logins, runs the doctor, asks before each change
headroom setup
# one block per account: percent used, reset time and pace state per window
headroom

Claude 的用量信息来自 Claude Code 的状态栏。将以下内容添加到 ~/.claude/settings.json（或其他每个配置文件的 settings.json），或者使用 headroom statusline --chain '<your command>' 串接现有状态栏命令：

{ "statusLine": { "type": "command", "command": "headroom statusline" } }

此外，Headroom 最多每 10 分钟运行一次 Claude Code 自带的 /usage（它会补充状态栏未提供的特定范围用量信息；状态栏在 claude -p 下不会运行，因此两次运行之间的数据可能会过时）。headroom doctor 和 headroom status 会显示当前使用哪种方式。Headroom 绝不会编辑你的 Claude 设置文件。

对于 Claude Code，请先通过 npm 或 Homebrew 安装 headroomd，再安装插件：

claude plugin marketplace add Apertur3/headroom
claude plugin install headroom@headroom

插件包含 Headroom 技能、MCP 服务注册，以及每次提示词中显示的配额信息。 同时使用它和 headroom hook install 不会重复打印配额信息。 有关要求和卸载命令，请参阅 Claude Code 插件。

已经在运行 Claude Code 或其他 Agent？将 skills/headroom/SKILL.md 复制到其技能目录，并说“set up headroom”。

如果不使用插件，headroom setup 会提供选项，为默认的 Claude Code 配置文件注册 MCP 服务。若要手动注册，或在其他配置文件中注册：

claude mcp add --scope user headroom -- headroom mcp
CLAUDE_CONFIG_DIR=~/.claude-work claude mcp add --scope user headroom -- headroom mcp

不支持 MCP 的 Agent（例如 Codex）可调用 CLI。然后向你的 Agent 提供 面向 Agent 的说明。MCP 工具和调用示例见 docs/mcp-and-agents.md。

headroom accounts discover   # finds Claude, Codex, Antigravity, Grok and Kimi logins

headroom setup                # discovery, doctor, service, MCP registration -- asks before each change

面向 Agent

将以下内容粘贴到 Agent 会读取的 CLAUDE.md 或 AGENTS.md 中，并将占位符替换为你自己的操作类别、计量项和 Agent 名称。之后，Agent 会在分派工作前检查 Headroom，而不是询问你。

## Usage limits (Headroom)

Check Headroom before you start work on a subscription. Do not ask me about usage or reset times.

- `headroom can <class> --owner <your-name>`: exit 0 means go, exit 2 means no. Any other exit
  is an error: treat it as no. Classes are the `[consumes]` entries in `~/.headroom/routing.toml`.
- On no, try the next class in your fallback list. If none has room, run
  `headroom wait --meter <meter> --until-reset --max 6h` (exit 3 means it timed out), then run
  `headroom can` again before you start anything.
- Start a job with
  `headroom run --meter <meter> --need <window>:<points> --owner <your-name> -- <command>`,
  for example `--need 5h:10` for 10 percent of the 5-hour window. It reserves the points, runs
  the command and releases them when it exits. Exit 2 means refused; otherwise it returns the
  command's own exit code.
- UNKNOWN means there is no trustworthy reading. Treat it as no. Never pass `--allow-unknown`
  unless I ask for it.
- For the full picture, read `headroom --json`, not the human view.
- In Claude Code with the Headroom MCP server, `quota_can` answers the same question as
  `headroom can`.

若要在每一轮都向 Agent 提供实时配额，请运行 headroom hook install --agent claude（或在 headroom setup 中回答 yes）。此后，每条 Claude Code 提示词都会附带一行由守护进程在上次轮询时写入的信息，并标明信息的时效；每轮约消耗 60 个 token。headroom line 会为任何 Agent 打印同一行。目前仅支持 macOS 和 Linux 上的 Claude Code；暂不支持 Windows、Codex 和 Gemini 钩子。

单独使用 can 仅供参考。预留会告知其他使用 Headroom 的 Agent 这些点数已被占用；它不会限制任务本身的消耗，也无法阻止不使用 Headroom 的工具。更详细的说明，包括节奏状态、租约和预留，请参阅 skills/headroom/SKILL.md。

平台支持和已知限制

_{来源：五种订阅服务（Claude、Codex、Kimi，以及实验性的 Antigravity 和 Grok）和两种本地服务类型（vLLM 和 llama.cpp）。读取结果过期或失败时会显示 UNKNOWN，绝不会显示数字。完整说明 · 复现步骤}

原因

需要同时启动多个任务的 Agent 首先要回答两个问题：此账户是否有能力承担这些任务，以及其他哪些任务已经预留了容量？供应商界面无法以编程方式回答这两个问题，而过时的读数可能会导致向容量已不足的账户分配更多工作。Headroom 将供应商读数与协作式预留结合起来。读数过期或获取失败时，它会显示 UNKNOWN，而不是数字；对于此类读数，can 会回答 NO，除非你传入 --allow-unknown。

一个守护进程会读取 Claude、Codex、Antigravity、Grok、Kimi 以及本地 vLLM 或 llama.cpp 池的配额，保留历史记录并检测重置。Antigravity 和 Grok 支持为实验性功能。

_{合成数据。终端使用真实 CLI，在模拟的主目录上运行；该目录由 scripts/render-demo-animated.mjs 生成。}

安装  ·  面向 Agent  ·  为何如此  ·  演示  ·  设计原则  ·  文档

与用量分析器有何不同

ccusage 等用量分析器会读取本地用量文件并报告估算费用。Headroom 从供应商自己的用量端点读取其报告的用量和限制，并在工作开始前给出答案：can、gate、route、租约和收件箱，供负责分派工作的 Agent 使用。它们回答的问题不同，可以并行使用。

使用前后对比

如果不进行检查，Agent 会在任务执行过程中撞上限额才发现问题。使用 Headroom 后，它会先检查；若答案为 NO，则尝试回退列表中的下一个类别。can 只进行检查；当多个任务同时启动时，请使用 headroom run，让每个任务都预留所需容量。

不使用 Headroom

# weekly limit reached mid-task, work stops half done
codex exec "refactor the billing module"

使用 Headroom

if headroom can codex-build --owner builder; then
  codex exec "refactor the billing module"
elif headroom can claude-fable --owner builder; then
  claude -p "refactor the billing module"
else
  # no class has room: wait for a reset, then check again before dispatching
  headroom wait --meter codex-main:main --until-reset --max 6h
fi

headroom run --meter ... --need ... --owner ... -- <command> 更进一步：它会先检查，再为任务运行期间预留容量，让其他使用 Headroom 的 Agent 看到该容量已被占用；随后运行命令并释放预留。examples/ 中提供了使用合成数据的可运行示例。

功能

仪表板

_{合成数据，由 scripts/render-dashboard-demo.mjs 生成。}

人工控制面板和浏览器报告

打开终端概览，或导出本地浏览器快照：

headroom dashboard
headroom dashboard --once --ascii

使用 Tab 选择一个仪表，按 v 查看详情，按 e 查看事件。两种图表视图都显示记录的剩余容量；读数缺失或不可信时，图表会出现空缺。

要在浏览器中打开相同的记录历史：

headroom dashboard --html report.html

在浏览器中打开生成的文件。报告会在概览中显示订阅用量和重置时间，并提供可选择的时间窗口图表和样本详情。报告支持浅色和深色主题，且不会发出外部请求。这是一份快照；要查看更新的读数，请重新生成报告。除非传入 --force，否则会保留现有文件；在支持 Unix 权限的系统上，新文件的权限模式为 0600。

设计原则

每一条都是代码强制执行、测试覆盖的规则。过去实际发生的问题正是制定每条规则的原因。

• 失败时从严处理：绝不提供虚假数字。 缺失、过时或不一致的读数会标记为 UNKNOWN；对此类读数，can 会返回 NO，除非你明确传入 --allow-unknown。
• 无法静音的过时通道预警。 通道连续 6 小时没有新鲜读数时，无论通知配置如何，都会触发警报。
• 只终止 Headroom 确认启动的进程。 在 macOS 和 Linux 上，只有记录的 pid、命令和启动时间仍匹配时，才会向进程发送信号。
• 机密信息保存在各自的存储中。 通知令牌保存在操作系统的机密信息存储中；供应商凭据在使用时从供应商自己的存储或凭据文件中读取，绝不会复制。输出内容经过脱敏处理。
• 每种过往故障都有一份脱敏样本。 在实际使用中遇到的每一种 Antigravity 故障形态，都有对应的样本和测试。

运行原理

Headroom 通过原生 TypeScript 适配器读取 Claude、Codex、Grok 和 Kimi。 Antigravity 为实验性支持，且仅支持 macOS 14 或更高版本：需要登录的 agy 和正在运行的 Headroom 守护进程。npm 和 Homebrew 软件包包含通用 macOS 读取器，使用前会通过 SHA-256 验证。消费者订阅无需也不支持 Gemini CLI； Google 于 2026 年 6 月 18 日结束了消费者使用 Gemini CLI 的权限。

对于 Antigravity 配额，捆绑的 macOS 读取器会在进程列表中查找正在运行的 Antigravity 语言服务器 （由守护进程保留的 agy），获取其本地端口；如果进程命令行中包含本地 CSRF 令牌，也会一并获取， 然后向 127.0.0.1 上的该服务器请求配额摘要。它不会读取 agy 的 OAuth 或会话凭据。守护进程还会读取 ~/.gemini/antigravity-cli/log 下 agy 最新日志的末尾部分，但仅用于查找登录状态标记。Headroom 绝不会读取 Gemini CLI 的 OAuth 文件。 缺失或读取失败的摘要会显示为 UNKNOWN。如果空闲窗口包含实际比例值，但其重置时间看起来是合成的， 则可能会带有存疑标记。若一次成功响应中完全没有五小时窗口（表示滚动窗口确实空闲），则显示 n/a 而不是 UNKNOWN，且不会阻止预算检查。端点契约和原生读取器基于 CodexBar（MIT）构建。

启动作业前检查预算

此合成示例的用量为 20%，另一个所有者预留了 75%。剩余容量不足以承载另一个 10 点的作业， 因此不会启动子命令：

$ headroom run --meter claude-main:all --need wk:10 --owner builder -- codex exec "Run the tests"
wk needs 10 more but only 0.0 left after 75.0% already leased before the 10% reserve

容量充足时，run 会预留容量、启动命令，并在命令结束时释放预留。检查和预留在多个进程间以原子方式执行。 普通的 can 或 gate 仅提供建议；启动工作时请使用 run 或 can --lease。这些预留用于协调使用 Headroom 的 Agent； 它们无法阻止无关工具消耗订阅额度。

示例

可直接使用合成数据运行，无需登录。构建一次，然后将 CLI 指向已填充数据的主目录：

npm run build
# sets HEADROOM_HOME to a throwaway demo home
eval "$(node scripts/demo-home.mjs)"
# walks a fallback list, dispatches on the first class with room
bash examples/orchestrator-loop.sh
# refuses a job the budget cannot cover (exit 1)
bash examples/ci-gate.sh
# the MCP call a client sends, over stdio
bash examples/mcp-quota-can.sh

除非 HEADROOM_HOME 指向该演示主目录，否则脚本不会运行，因此不会触碰真实的 ~/.headroom；它们调用的是仓库构建产物（dist/cli.js），而不是全局安装的 headroom。它们会打印所用的 二进制文件。

脚本以及初始版 accounts.toml、policy.toml 和 routing.toml 文件请参见 examples/。

文档

• docs/claude-code-plugin.md：Claude Code 插件安装、配额行、MCP 和卸载
• docs/quickstart.md：从安装到显示首条真实数据，涵盖 macOS、Linux 和 Windows
• docs/concepts.md：主体、计量项、窗口、观测值、节奏状态、租约、事件
• docs/mcp-and-agents.md：MCP 工具、调用示例，以及编排器应如何使用它们
• docs/json-contract.md：每项 --json 输出和 MCP 工具结果按版本定义的字段结构，以及兼容性承诺
• docs/vendors.md：Headroom 从各供应商处读取的内容，以及已知的实时限制

对比与读取内容

Headroom 不是成本追踪器：ccusage 根据本地日志估算支出，而 headroomd 读取供应商执行的限额。两者可以并行使用。

Headroom 是非官方工具。默认情况下，它通过 Claude Code 本身读取 Claude；其他读取器使用你自己的登录信息访问未公开的供应商端点。请参阅供应商端点和你的账户。

厂商端点与您的账户

_{这是一个独立的开源项目，与 Anthropic、OpenAI、Google、xAI 或 Moonshot AI 无关联、未获其赞助，也未获其认可。若干集成会使用需要您自行登录的厂商未公开端点：请参阅 厂商端点与您的账户。Claude、Codex、Antigravity、Grok 和 Kimi 是各自所有者的商标，在此仅用于指代 Headroom 读取数据的服务。这是 npm 包 headroomd（代码仓库 Apertur3/headroom），与其他名为 Headroom 的项目无关，例如上下文压缩库 headroomlabs-ai/headroom。}

若干适配器会读取厂商未作为公共 API 公开文档的用量端点。Headroom 使用您自己的凭据调用这些端点；凭据取自您在同一台机器上安装并登录的厂商 CLI，且仅用于读取用量：它不会发送提示词、修改任何账户设置，也绝不会写入其他工具的凭据存储。仅可将其用于您拥有的账户。厂商条款可能限制此类访问，厂商也可能随时更改或封锁端点；使用风险由您自行承担。Headroom 不会轮换凭据以绕过封锁或限制。仅可使用您拥有的账户；Headroom 不会帮助规避厂商限制。

每个请求都会标明自身身份为 headroomd/<version>。默认设置（claude_probe = false）无需令牌，也不会调用未公开端点：Headroom 会读取状态栏快照，或运行 Claude Code 自带的 /usage，且绝不会读取 Claude 的 Keychain 项或调用 Anthropic。将 claude_probe = true 设为启用状态，即表示选择使用最后手段：仅在没有其他可用读取方式时，Headroom 才会读取 Claude Code 的 OAuth 令牌并调用 Anthropic 的未公开端点；Anthropic 的条款规定，此登录仅供日常使用 Claude Code。

安全性

Headroom 绝不会将供应商凭据或通知令牌写入磁盘，并会从输出中删去机密信息。在 macOS 上启用 claude_probe = true 时，随附的辅助程序 headroom-claude-probe 会运行 /usr/bin/security 来读取 Claude Code 的 Keychain 令牌；Keychain 项目自身的访问控制列表允许此操作。辅助程序会将令牌保存在自身内存中，并自行发起用量请求，因此令牌不会传递给 Node，也不会出现在 Headroom 的输出中。在 macOS 26.5 上使用 Claude Code 2.1.263 时，无需显示 Keychain 对话框。该辅助程序以通用二进制文件的形式包含在 npm 软件包中，每次使用前都会根据记录的 SHA-256 校验其完整性。其他情况下，令牌会在调用时从供应商自身的凭据文件中读取，并在请求后立即丢弃。守护进程在 macOS 和 Linux 上监听权限为 0600 的本地套接字。在 Windows 上，它使用命名管道，通信双方都必须证明持有每个守护进程专属的会话令牌；该令牌保存在 HEADROOM_HOME 下权限为 0600 的文件中。没有遥测功能。除了你配置的供应商和启用的通知渠道外，Headroom 唯一会主动发出的请求是上文提到的每日 npm 版本检查，它是一个不包含账户数据的普通 GET 请求（设置 update_check = false 可将其关闭）；只有在你运行 headroom update 和 headroom engine install 时，它们才会联系 npm 和 GitHub。引擎版本已固定并通过校验和验证，每次查询都会写入审计日志。详情请见 SECURITY.md。

状态

版本以 headroomd 的名称发布到 npm；CHANGELOG.md 列出了每个版本的变更。供应商端点不公开且可能随时更改：Headroom 会固定端点、记录测试样本、在收到 401、403 和 429 响应时退避，并在数据过时时显示 UNKNOWN。有关已验证和未验证的内容，请参阅平台支持与已知限制。Antigravity 需要 macOS 和由守护进程保管的 agy；请参阅供应商设置。

欢迎贡献：请参阅 CONTRIBUTING.md 和标记为适合初次贡献者的问题。

MIT。第三方声明见 THIRD_PARTY_NOTICES.md。