headroom

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
    <img alt="headroom: a fuel gauge for AI coding agents" src="docs/assets/banner-light.svg" width="640">
  </picture>
</p>

**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.

<p align="center">
  <img alt="Terminal demo: Headroom checks Claude and Codex quota, waits or reroutes when needed, and reserves capacity before a job" src="docs/assets/headroom-demo.gif" width="720">
</p>

```sh
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):

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

<p align="center">
  <a href="https://github.com/Apertur3/headroom/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/Apertur3/headroom/ci.yml?branch=master&style=flat-square&label=CI"></a>
  <a href="https://www.npmjs.com/package/headroomd"><img alt="npm version" src="https://img.shields.io/npm/v/headroomd?style=flat-square&label=npm"></a>
  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/badge/license-MIT-blue?style=flat-square"></a>
</p>

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

Not a cost tracker: [ccusage](https://github.com/ccusage/ccusage) estimates spend from local logs; headroomd reads the limit the vendor enforces. They work side by side.

Unofficial; some readers use undocumented vendor endpoints with your own login. See [Vendor endpoints and your accounts](#vendor-endpoints-and-your-accounts).

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.

```sh
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
```

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

```sh
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](docs/claude-code-plugin.md) for requirements and uninstall commands.

Already running Claude Code or another agent? Copy [skills/headroom/SKILL.md](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:

```sh
claude mcp add --scope user headroom -- headroom mcp
CLAUDE_CONFIG_DIR=~/.claude2 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](#for-agents). The MCP tools and example calls are in
[docs/mcp-and-agents.md](docs/mcp-and-agents.md).

<details>
<summary>Manual setup and optional configuration</summary>

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

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

On macOS and Linux, `brew install apertur3/tap/headroom` installs the same package and adds a
`brew services start headroom` service.

By hand, the same steps are one command:

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

Run `headroom notify configure` to choose notification channels, a preset and overrides. Run
`headroom update` only when you choose to install a newer package; `headroom uninstall` reverses
setup, and `headroom completion <bash|zsh|fish|pwsh>` prints a shell completion script.

`accounts discover` prints what it wrote (`Wrote ~/.headroom/accounts.toml (4 accounts). Next: headroom
doctor`) and, the first time, seeds `~/.headroom/policy.toml` and `routing.toml` from `examples/` so
`headroom can <class> --owner <your-agent-name>` works immediately with the example action classes (`claude-fable`, `codex-build`,
`gemini-bulk`) -- edit `routing.toml` to match your accounts.

Keep an optional second profile that is deliberately logged out without polling it: add
`enabled = false` to its `[[accounts]]` block, or run `headroom accounts disable <name>`.
It remains configured and can be restored with `headroom accounts enable <name>`.

Full walkthrough, including what each step grants and why: [docs/quickstart.md](docs/quickstart.md).

`status`/`doctor` check the npm registry at most once a day (a plain GET of the `headroomd`
version, no account data) and print a one-line notice when a newer `headroomd` is out; run
`headroom update` (never automatic) to install it. Set `update_check = false` in
`~/.headroom/policy.toml` to turn the check off -- see
[Staying up to date](docs/quickstart.md#staying-up-to-date).

</details>

---

## For agents

Paste this into the `CLAUDE.md` or `AGENTS.md` your agents read, and replace the placeholders with
your own action classes, meters and agent name. The agent then checks Headroom before it dispatches
work, instead of asking you.

```markdown
## 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`.
```

To put live quota in front of the agent on every turn, run `headroom hook install --agent claude`
(or answer yes in `headroom setup`). Each Claude Code prompt then carries one line the daemon wrote at
its last poll, with its age, for about 60 tokens per turn; `headroom line` prints the same line for any
agent. Claude Code on macOS and Linux only for now; Windows, Codex and Gemini hooks are not supported yet.

A plain `can` is advisory. A reservation tells other agents that use Headroom the points are taken;
it does not limit what the job itself spends, and it cannot stop tools that do not use Headroom.
The longer version, with pace states, leases and reserves, is
[skills/headroom/SKILL.md](skills/headroom/SKILL.md).

---

## Platform support and known limitations

<table align="center">
  <tr>
    <td align="center"><b>7</b><br><sub>sources read</sub></td>
    <td align="center"><b>3</b><br><sub>OSes tested in CI</sub></td>
    <td align="center"><b>1</b><br><sub>local daemon, one call per decision</sub></td>
    <td align="center"><b>0</b><br><sub>telemetry (one opt-out update check)</sub></td>
  </tr>
</table>

<p align="center">
  <sub>Sources: five subscription services (Claude, Codex, Kimi, and the experimental Antigravity and Grok) and two local server types (vLLM and llama.cpp). A stale or failed reading prints <b>UNKNOWN</b>, never a number. <a href="docs/verification.md">Full writeup</a> &middot; <a href="docs/verification.md#reproduce-it">Reproduce it</a></sub>
</p>

| Platform | Status |
|---|---|
| macOS | The primary platform: daily use on one machine, plus CI. Antigravity needs macOS 14 or later |
| Linux | CI on Ubuntu; cold install also checked by hand on ARM64 |
| Windows | **Experimental.** Tests run in CI. On Windows 11, `headroom install-service` registers a "Headroom Daemon" task that starts immediately and serves a per-user named pipe whose name is a hash only. `headroom uninstall --home` asks the running daemon to shut down over that pipe, removes the task and the home, and exits 0. After an in-place upgrade, `headroom install-service` restarts the daemon onto the new version, except a daemon started by 0.2.6 or older, which has no shutdown request and must be stopped by hand once (end node.exe in Task Manager). Verified on Windows 11: MCP registration (`claude mcp add --scope user headroom -- headroom mcp` shows Connected) and a real Claude login read (fresh on the first poll). Not verified on Windows: a slow stop (the 27 second wait is covered by unit tests only) and start at logon and across reboots. Full detail below |
| Antigravity | Experimental. Depends on a private local endpoint that the vendor can change |
| Grok | Experimental. Reads the Grok CLI's undocumented chat-proxy endpoint and presents itself as the Grok CLI |

<details>
<summary>The full table: tests, CI, install checks, Windows, vendor endpoints</summary>

| | |
|---|---|
| Tests | `npm test` (vitest), run on every push on macOS, Ubuntu and Windows; some tests are POSIX-only and skip on Windows. Current counts are in the CI logs; method and limits: [docs/