Headroom

Privacy policy

Your data stays on your Mac.

Headroom collects nothing. This policy explains what the app reads, what it writes, when it talks to GitHub, and what this website logs.

Effective September 26, 2026

The short version

  • Headroom collects no data. No analytics, no tracking and no Headroom account.
  • Local by default. Everything about Claude and Codex comes from files those tools already write on your Mac, and the app makes no network requests for them.
  • GitHub only if you connect it. To show GitHub Copilot’s usage, which is kept on GitHub, Headroom talks to GitHub, and only to GitHub, after you connect your account.
  • Nothing reaches us. There is nothing for us to see, share or sell.

What the app reads

The Mac App Store version of Headroom runs in Apple’s app sandbox, so it can only read folders you choose. It asks for each one once, in a standard macOS folder picker, and only for folders that exist on your Mac:

  • ~/.claude, Claude Code’s folder. Headroom reads the session files in ~/.claude/sessions to see which sessions are running, their names, project folders and status. From the end of each session’s transcript in ~/.claude/projects it reads the token counts and model name, to show how full the context is. It doesn’t keep or show the text of your conversations. It asks for read and write access to this folder only for the optional Connect terminal feature, below.
  • ~/Library/Application Support/Claude, read only. Headroom reads plan-usage-history.json, where the Claude desktop app records your 5-hour and weekly plan usage. While a Claude app session is under Just finished, it also reads the start of that app’s session files in claude-code-sessions for one field, lastFocusedAt, to see when you last opened each session there.
  • ~/.codex, OpenAI Codex’s folder, read only and only if you track Codex. Headroom reads Codex’s session files in ~/.codex/sessions for your Codex limits, which threads are running and how full their context is, plus the thread titles Codex keeps. It uses only the fields it needs and never keeps or shows your prompts or Codex’s replies. While a Codex app thread is under Just finished, it reads the list of unread thread ids in .codex-global-state.json, and nothing else from that file. It never opens auth.json (your Codex sign-in) or Codex’s configuration.
  • ~/.copilot, only if you choose Connect sessions, below. There Headroom reads only the small records its own hook writes, and the names (not the contents) of Copilot’s log files, to tell which sessions are still running.

Headroom reads these files on your Mac while it runs, to draw the pill, the panel and the widgets. It doesn’t copy them anywhere and keeps no history of them.

What the app stores

  • Its own settings, such as launch at login and whether moments show, and the folder permissions you granted. macOS keeps them in the app’s own container, ~/Library/Containers/com.niomartinez.headroom.
  • A small summary for the widgets: your limits, and your sessions without their process ids or folder paths (and without their names, if you turn names off in Settings). It lives in the app’s shared container, ~/Library/Group Containers/L237BMXGB6.com.niomartinez.headroom, which only Headroom and its widgets can read.
  • If you connect GitHub, your GitHub sign-in (an access token and a refresh token) in Headroom’s own item in your Mac’s keychain, and your GitHub username in its settings.

Deleting the app can leave those folders behind; if they’re still there, you can delete them too. Support explains how.

Connect terminal (optional)

Claude Code in the terminal doesn’t write its plan limits to a file on its own. If you click Connect terminal and confirm the dialog that lists every change, Headroom:

  • backs up ~/.claude/settings.json to ~/.claude/settings.json.headroom-backup first;
  • adds a status line and hooks to ~/.claude/settings.json, keeping your own status line working and every other setting as it was;
  • writes a small script, ~/.claude/headroom/bridge.sh, that Claude Code runs.

The script writes small status files to ~/.claude/headroom on your Mac, for Headroom to read: session ids, folder paths, event names, and context and limit numbers. It never saves your prompts. Disconnect terminal removes exactly what was added, restores your original status line and deletes ~/.claude/headroom.

Disconnect before you delete Headroom. If you don’t, the script keeps writing those files until both the app and its container are gone. Support explains how to clean up.

Connect Copilot sessions (optional)

To show GitHub Copilot desktop or CLI sessions, click Connect sessions… under Session activity and grant access to ~/.copilot if asked. Confirm the dialog that lists every change. Headroom adds two things, leaving your own Copilot settings alone:

  • ~/.copilot/hooks/headroom.json, its own hook file, which Copilot reads when a session starts;
  • a small script in ~/.copilot/headroom, which those hooks run.

The script writes one small record per session to ~/.copilot/headroom/sessions: the session id, its folder path, the event name and notification type, and process ids. It never saves your prompts. Headroom never opens Copilot’s own config.json, settings or session history. Disconnect under Session activity removes both again. New sessions load the connection; GitHub sign-in for usage is separate.

Copilot usage and GitHub (optional)

GitHub Copilot’s usage is kept on GitHub, not on your Mac. If you click Connect GitHub, you sign in on github.com with GitHub’s device code, and grant Headroom’s own GitHub app read-only access to your plan’s billing. Headroom never uses the sign-in of the GitHub CLI, VS Code or Copilot.

  • Headroom then connects to github.com (to sign in and renew the sign-in) and api.github.com, about every 15 minutes, and to nothing else.
  • It sends your sign-in token and the current year and month. It receives your GitHub username and this month’s Copilot usage: on a seat an organization pays for, that seat’s plan and monthly credits.
  • Nothing goes to the developer or anyone else. GitHub’s own privacy terms apply to your GitHub account.
  • Disconnect deletes the token from your Mac. To revoke the grant on GitHub too, go to github.com/settings/apps/authorizations.

Network and third parties

Apart from GitHub, if you connect it, the app doesn’t connect to the internet. It contains no analytics, advertising or crash reporting code from anyone. If you share analytics with app developers in macOS (System Settings, Privacy & Security, Analytics & Improvements), Apple may pass on anonymous crash reports. Apple controls that, and you can turn it off there.

This website

headroom.niomartinez.com is a static website hosted on Vercel. It sets no cookies and uses no analytics or tracking scripts. Like any web host, Vercel may log standard request data, such as your IP address, browser, the page you asked for and the time, to deliver the site and keep it secure. See Vercel’s privacy policy.

If you email us, we use your message and address only to reply, and don’t share them.

Children and changes

Headroom isn’t directed at children, and it collects no data from anyone. If this policy changes, the new version will be posted on this page with a new effective date.

Contact

Headroom is made by Nio Martinez. Questions about privacy go to hello@niomartinez.com.