headroom — Claude Code MCP server: subscription limits
Reports what is left in the 5-hour and weekly windows of a Claude or Codex subscription, plus reset times, so agents can check before starting a job.
claude mcp add headroom -- npx -y headroomdWhat headroom does
headroom pulls the limit readings your Claude and Codex subscriptions expose and turns them into go, wait or reroute. You can read that over the CLI or as MCP tools.
Claude numbers arrive through the statusline: point statusLine in ~/.claude/settings.json at headroom statusline. The tool also calls Claude's own /usage no more than once per 10 minutes to pick up scoped meters the statusline misses. It leaves your Claude settings files untouched.
You need Node 22.13 or newer and the headroomd package, which provides the headroom command; headroom setup then locates logins and runs a doctor pass. Agents without MCP, Codex among them, call the CLI instead, so paste the headroom can and headroom run instructions into CLAUDE.md or AGENTS.md. Without that block the agent never asks about quota and will start a job on an exhausted window.
What it helps with
- see when the 5-hour window runs out
- hold off a build when quota is short
- move an agent to another class once a meter is empty
- reserve part of a window for one job
- check the weekly allowance before starting
Example prompts for the agent
- Check my subscription limits with headroom and tell me whether I can start the build
- Run this through
headroom run --meter 5h --need 5h:10 --owner my-agent -- npm test - Wait for the reset, then recheck with
headroom canbefore doing anything
How to install headroom
Platform CLI
claude mcp add headroom -- npx -y headroomdPlatform CLI
codex mcp add headroom -- npx -y headroomdConfig file
{
"mcpServers": {
"headroom": {
"command": "npx",
"args": [
"-y",
"headroomd"
]
}
}
}Config file
{
"servers": {
"headroom": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"headroomd"
]
}
}
}Platform CLI
gemini mcp add headroom npx -y headroomdStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about headroom
How do I install headroom in Claude Code?
Install the CLI first with npm install -g headroomd or brew install apertur3/tap/headroom and run headroom setup. Then register the server with claude mcp add headroom -- npx -y headroomd.
What does headroom do?
It reads the limit data reported by Claude and Codex subscriptions and returns how much of the 5-hour and weekly windows is used, with reset times. An agent can query it before dispatching work.
Is headroom the same as headroomlabs-ai/headroom?
No. The headroomlabs-ai project compresses context, while this one tracks subscription limits. Both repos say they are unrelated.
