Headroom MCP server

Your coding agents check their Claude and Codex limits before they start a job.

headroomd reads the 5-hour and weekly limits your subscriptions report and answers go, wait or reroute, over the CLI or MCP.

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

Then install the Claude Code plugin (requires headroomd above):

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

macOS, Linux, Windows (experimental). No telemetry. Zero runtime dependencies.

Not related to headroomlabs-ai/headroom, the context-compression project.

Install

Node 22.13 or newer. The npm package is headroomd; the Homebrew formula is apertur3/tap/headroom. Both install the headroom command.

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 usage comes from Claude Code's statusline. Add this to ~/.claude/settings.json (or the settings.json of each other profile), or chain an existing statusline with headroom statusline --chain '':

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

Alongside it, Headroom runs Claude Code's own /usage at most every 10 minutes (it adds the scoped meters the statusline does not carry; the statusline never runs under claude -p, so it can go stale between runs). headroom doctor and headroom status say which is in use. Headroom never edits your Claude settings files.

For Claude Code, install the plugin after installing headroomd with npm or Homebrew:

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

It bundles the Headroom skill, the MCP server registration and a quota line on every prompt. Using it alongside headroom hook install does not print the quota line twice. See Claude Code plugin for requirements and uninstall commands.

Already running Claude Code or another agent? Copy skills/headroom/SKILL.md into its skills directory and say "set up headroom".

Without the plugin, headroom setup offers to register the MCP server for your default Claude Code profile. To register it by hand, or in another profile:

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

Agents without MCP, Codex for example, call the CLI. Then give your agents the instructions in For agents. The MCP tools and example calls are in docs/mcp-and-agents.md.

Manual setup and optional configuration

The three commands above are the short path. Discovery on its own:

Shortened. The full README is on GitHub.