Privacy & Data

What Headroom reads, what it sends.

Last updated: 2026-05-06

Headroom is a macOS menu-bar app that displays the rate-limit headroom for Claude Code and the Codex CLI. It is an independent, open-source project and is not affiliated with Anthropic or OpenAI.

The summary: Headroom runs entirely on your machine. It reads the local credentials Claude Code and Codex already store on this device, calls each service's own usage endpoint, and displays the result. There is no Headroom-operated server, no analytics, no telemetry, and no third-party data collection.

What Headroom reads from your machine

From your home directory:

~/.codex/auth.json — the OAuth bearer token and ChatGPT account ID written by the Codex CLI when you sign in.
~/.codex/sessions/**/*.jsonl — the rate-limit snapshots Codex persists per session. Used only as a fallback when the live endpoint is unreachable.
~/.claude/projects/**/*.jsonl — the local conversation logs Claude Code writes per project. Used only as a fallback estimator when the live endpoint is unreachable, and only to count tokens.

From the macOS keychain:

The keychain item with service name Claude Code-credentials — the OAuth bearer token written by Claude Code when you sign in.

What Headroom sends over the network

Two HTTP requests, both to the services that issued the tokens above:

GET https://api.anthropic.com/api/oauth/usage — the same endpoint Claude Code's /usage command calls. Authorized with the Claude bearer token.
GET https://chatgpt.com/backend-api/wham/usage — the same endpoint the Codex CLI calls on launch. Authorized with the Codex bearer token and ChatGPT account ID.

That is the complete list. Headroom does not transmit your tokens, your usage, your machine identifiers, or anything else to any other server. Both requests are throttled internally to once every five minutes and cached on disk so the app can keep working under rate limits.

Where data is stored

~/Library/Caches/Headroom/ — the most recent JSON response from each service, used for fallback when the API is unavailable. Delete it any time via Settings ▸ Reset caches.
~/Library/Application Support/Headroom/state.json — the snapshot the menu bar and widget read from. Contains percentages and reset times, no tokens.

Third-party terms

Anthropic updated its terms in February 2026 to restrict third-party use of Claude subscription OAuth tokens to Anthropic's own products (Claude Code and the Claude.ai web interface). Headroom uses those tokens to display your own usage, on your own machine. Whether that constitutes a permitted use is a question between you and Anthropic; running Headroom is at your discretion.

OpenAI's terms similarly restrict subscription-credential reuse in third-party software. The same caveat applies.

No tracking, no accounts, no analytics

Headroom has no account system, no crash reporter, no analytics SDK, no advertising identifiers, and no third-party network calls beyond the two endpoints listed above. The source code is published in full at github.com/nvbinh15/headroom and you are encouraged to verify these claims against it.

Contact

Open an issue at github.com/nvbinh15/headroom/issues.