What it does
headroomd reads the 5-hour, weekly and monthly limits reported by Claude, Codex and Kimi, with Antigravity and Grok marked experimental, and checks whether local vLLM or llama.cpp servers are free. For each request it answers go, wait or reroute, and it can be queried through the CLI or MCP. A stale or failed reading is shown as UNKNOWN rather than a number.
Coding agents can check this before they dispatch work, using instructions pasted into their CLAUDE.md or AGENTS.md file. For Claude Code, a bundled plugin adds the skill, the MCP registration and an optional quota line on every prompt. Agents without MCP support can call the CLI instead. Reservations let other agents that use the tool see that points are taken, though they do not cap what a job spends.
The tool needs Node 22.13 or newer and is installed through npm or Homebrew. Claude usage is read from Claude Code's statusline and, at most every 10 minutes, from its /usage command. It never edits Claude settings files and sends no telemetry, apart from one daily opt-out update check. It has zero runtime dependencies, and CI tests cover macOS, Linux and Windows.
Limitations and requirements
Requires Node 22.13 or newer. The Claude Code plugin requires headroomd to be installed first. Windows support is experimental. Antigravity needs macOS 14 or later. Grok and Antigravity are experimental. The Claude Code quota line hook is supported only on macOS and Linux; Codex and Gemini hooks are not supported. The statusline does not run under claude -p, so readings can go stale between runs. Reservations are advisory and cannot stop tools that do not use Headroom. The daily update check can be turned off with a setting.
Safety
Our team has not reviewed this resource. Only automated rules checked it; resources with high-risk signals are not published. These are signals, not a guarantee that installing it is safe. Try it in a sandbox project first.
- Runs code or changes an assistant's behaviour
Sources
- Official MCP Registry first seen 13 Nov 2026 · last seen 13 Nov 2026 · its page on the source
io.github.Apertur3/headroom
Live subscription limits, resets and budget checks for coding agents over MCP.
v0.2.23As shown on registry.modelcontextprotocol.io when we last read it