# headroom

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.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 30
- Author: Apertur3
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/Apertur3/headroom
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/headroom

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add headroom -- npx -y headroomd
```

### Codex

**Platform CLI**
```bash
codex mcp add headroom -- npx -y headroomd
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "headroom": {
            "command": "npx",
            "args": [
                "-y",
                "headroomd"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "headroom": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "headroomd"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add headroom npx -y headroomd
```

## When to use it
- 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
- 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 can` before doing anything

## Similar
- [quota-axi](https://affpapa.org/en/nevibecode/skills/quota-axi.md) — skill · 1300 installs
- [cli-resilience](https://affpapa.org/en/nevibecode/skills/cli-resilience.md) — skill · 976 installs
- [sales-quota-setting](https://affpapa.org/en/nevibecode/skills/sales-quota-setting.md) — skill · 25800 installs
- [quota-setting-calculator](https://affpapa.org/en/nevibecode/skills/quota-setting-calculator.md) — skill · 309 installs
- [astrale-cli](https://affpapa.org/en/nevibecode/skills/astrale-cli.md) — skill · 1800 installs
- [flow-status](https://affpapa.org/en/nevibecode/commands/flow-status.md) — command · 1514 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md