Privacy & Data

What Headroom reads, what it sends.

Last updated: 2026-05-17

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

The summary: Headroom runs entirely on your machine. It reads the local credentials Claude Code, Codex, and Cursor 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/.credentials.json — the OAuth bearer token written by Claude Code on versions that store credentials on disk.
~/.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.
~/Library/Application Support/Cursor/User/globalStorage/state.vscdb — the SQLite database where Cursor IDE stores its OAuth bearer token (cursorAuth/accessToken) and refresh token.
~/Library/Application Support/Headroom/claude-credentials.json — Headroom's local copy of the Claude OAuth blob. Written after the first successful read so timer refreshes don't repeatedly ask macOS for Claude Code keychain access.

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. Headroom reads this at most once (or again after an API 401), then caches it to the file above.
The keychain items cursor-access-token and cursor-refresh-token — OAuth tokens written by the Cursor CLI when present.

What Headroom sends over the network

HTTP requests 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.
POST https://api2.cursor.sh/aiserver.v1.DashboardService/GetCurrentPeriodUsage — Cursor's dashboard usage endpoint. Authorized with the Cursor bearer token.
GET https://api2.cursor.sh/auth/usage — legacy request-based usage for some enterprise plans. Authorized with the Cursor bearer token.
POST https://api2.cursor.sh/oauth/token — refreshes an expired Cursor access token when a refresh token is available. Headroom writes the new token back to the same local store it was read from.

That is the complete list. Headroom does not transmit your tokens, your usage, your machine identifiers, or anything else to any other server. 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.
macOS keychain service Headroom-ClaudeCredentialsCache — legacy local copy; newer builds prefer claude-credentials.json instead.
~/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.

Cursor's usage endpoints are undocumented and may change without notice. Headroom reads the same local credentials and calls the same endpoints other community tools use to display your own usage on your own machine.

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