Headroom

Support

Help with Headroom.

Get Headroom free from the Mac App Store. Requires macOS 14 or later.

Most questions have a quick answer below. If yours doesn’t, write to hello@niomartinez.com and you’ll hear back from the person who makes Headroom.

Email support

Include your macOS version, and which tools you use Headroom with: the Claude app, Claude Code in a terminal, Codex or Copilot. Screenshots show session names, so crop what you’d rather keep private.

hello@niomartinez.com

Quick fixes

Headroom needs macOS 14 or later. None of these involve a Headroom account.

First launch: choose a tool or try sample data

Choose Claude, Codex or Copilot in the welcome window. Connect what you use, then choose Add another tool or Done. Every connection is optional. You can choose Set up later or Try sample data before granting access to anything.

To return, open Headroom from Applications, then choose General > Set up tools…. Existing connections stay in place. For Copilot, GitHub sign-in connects usage; Session activity connects desktop and CLI sessions separately. Start a new Copilot session after connecting it.

The pill is missing

Open Headroom from Applications in Finder. Opening it again brings up Settings. On macOS versions with System Settings > Menu Bar > Allow in the Menu Bar, make sure Headroom is on. If you use a menu bar manager, check its hidden items too.

After changing displays, the menu bar may have less space. Close other menu bar items, then Command-drag Headroom toward the clock when it appears. You can also choose Always compact in Headroom’s Settings.

Headroom does not require Claude or Codex’s own menu bar icons to be enabled. If toggling another app hides Headroom, or you see duplicate Headroom entries after using development builds, macOS may have kept an old permission association. Open the installed copy from Finder and contact supportif it continues. Include your macOS version and a screenshot of the switches.

No rings, no sessions: grant folder access

Headroom can only read folders you allow. Click its pill in the menu bar, then Give access, or open Settings from the gear menu, choose Tools and click Grant access next to each folder. The folder picker opens in the right place, so you only confirm.

  • ~/.claude for Claude Code sessions and context.
  • ~/Library/Application Support/Claude for the plan limits the Claude desktop app records.
  • ~/.codex for Codex limits and sessions, if you track Codex. Read only.

Headroom only asks for folders that exist. If Settings says Claude Code, the Claude desktop app or Codex isn’t found, that folder isn’t needed yet.

The rings say “as of”

“As of 42m ago” means the newest usage reading is more than 30 minutes old, so the rings are drawn faded. The limits come from the Claude desktop app, which records them about every 15 minutes while it’s open, or from connected terminal sessions as they run. Open the Claude app, or keep working in a connected terminal session, and the rings catch up.

Codex records its limits only while you use it, so its rows often say “as of”. While no Codex session is running on this Mac, nothing here can have changed them, so the ring isn’t faded; it fades only when Codex is running and the number hasn’t caught up. They catch up the next time you use Codex. A limit that has reset since then reads 0% reset since last reading.

A tilde before a reset time, as in resets ~Sun 7 PM, means Headroom worked it out from your usage history instead of reading an exact time.

Terminal sessions or limits are missing: connect the terminal

Click the pill, then the gear, then Connect terminal, and confirm. Headroom backs up ~/.claude/settings.json first, adds a status line and hooks, and keeps your own status line working. Sessions you start after connecting show up with their limits and status. Restart sessions that were already running.

Disconnect the terminal

Gear menu, then Disconnect terminal. It removes exactly what Connect terminal added to ~/.claude/settings.json, restores your original status line, and deletes ~/.claude/headroom.

Copilot desktop and CLI: connect session activity

Open Settings, choose Tools, turn on Track Copilot. Under Session activity, click Connect sessions…, grant access to ~/.copilot if asked, and confirm the changes. Headroom adds one hook file and a small script there. Start a new Copilot desktop or CLI session to load the connection; existing sessions do not pick it up immediately. If the row offers Update…, update it and start a new session. GitHub sign-in alone does not connect sessions or completion moments. To undo the connection, click Disconnect in the same row.

Copilot usage: connect GitHub

In Settings, Tools, GitHub Copilot, click Connect GitHub. Headroom shows a code: click Copy Code and Open GitHub, paste it on GitHub and approve. If the Plan picker appears, choose the plan you pay for so Headroom can show a percent. When GitHub supplies an organization seat’s allowance, no plan choice is needed.

If an organization pays for your seat, Headroom shows that seat’s monthly credits. “No usage billed to you this month” means GitHub has no Copilot usage on your own account this month and shared no organization seat. To stop, click Disconnect; to revoke the grant on GitHub too, go to github.com/settings/apps/authorizations.

Add the widgets

Control-click the desktop, choose Edit Widgets and search for Headroom (or edit Notification Center the same way). Limits shows the rings, Sessions what’s running. A widget that says Open Headroom or Headroom isn’t running needs the app open: macOS refreshes widgets on its own schedule, so give it a few minutes. To hide session names in widgets, turn off Show session names in widgets in Settings.

Sessions you don’t recognize: sample data

Choose Try sample data in setup, or Preview with sample data in an empty panel, to see made-up sessions and limits. The same switch is in Settings, as Show sample data. While it’s on, the panel footer reads Sample data · Turn off. Click Turn off to go back to your own data.

Turn off moments

Don’t want the pill to widen when a session finishes or needs you? Open Settings from the gear menu and turn off Show moments. To stop “needs you” from staying in the menu bar until you look, turn off Keep “needs you” in the menu bar until I look. When you answer directly in Codex and the task resumes, the notice clears on Headroom’s next refresh, normally within two seconds after Codex writes the updated session event. If the tool still reports an old request, hover the session in the panel and click Dismiss.

Open Settings > General > Menu bar and choose a Display setting. Automatic expands task titles when space allows and keeps every gauge you selected. Always compact keeps one gauge; click the pill to read full titles in the panel.

macOS decides which menu bar items fit. Hold Command and drag Headroom toward the clock to give it a better position when space is tight.

Percentages beside the rings

A tool’s percentage appears when its highest usage reaches 75%, when its ring turns orange. At 95%, it turns red. With One gauge per tool enabled, each Claude, Codex and Copilot gauge shows its own warning percentage, even if another tool is closer to its limit. Below 75%, the rings stay visible without a number. Always compact keeps the single gauge chosen under Rings show.

Codex tasks already running when Headroom opens

Headroom recovers their status from local session history, so you don’t need to restart your Codex tasks. Very long histories can take more than one refresh to catch up. If a task is still missing, check that Track Codex is on and its folder access is granted in Settings > Tools.

Quit or uninstall

To quit, click the pill, then the gear, then Quit Headroom. To stop it from opening when you log in, turn off Launch at login in Settings.

To uninstall:

  1. If you connected the terminal or Copilot sessions, choose Disconnect terminal and Disconnect under Copilot’s Session activity first. That removes the status line and hooks (the bridge) from ~/.claude/settings.json and deletes ~/.claude/headroom, and removes ~/.copilot/hooks/headroom.json and ~/.copilot/headroom.
  2. If you connected GitHub, choose Disconnect in Settings, Tools, GitHub Copilot. To revoke the grant on GitHub too, go to github.com/settings/apps/authorizations.
  3. Quit Headroom.
  4. Move Headroom from your Applications folder to the Trash.
  5. To remove its settings and the widgets’ summary too, delete ~/Library/Containers/com.niomartinez.headroom and ~/Library/Group Containers/L237BMXGB6.com.niomartinez.headroom if they’re still there. In the Finder, choose Go › Go to Folder and paste each path.

Already deleted it without disconnecting? The status line and hooks stay in ~/.claude/settings.json, and the bridge keeps writing its status files until both the app and its container (step 5) are gone. After that it writes nothing and only runs the status line you had before, if any. To remove the entries, install Headroom again and choose Disconnect terminal. Copilot’s hook works the same way: it stops writing once Headroom and its container are gone, and Disconnect under Session activity, or deleting ~/.copilot/hooks/headroom.json and ~/.copilot/headroom, removes it.

FAQ

Where do I get Headroom?

Download Headroom free from the Mac App Store using the download button on the Headroom home page. It runs on macOS 14 Sonoma or later.

Is Headroom made by Anthropic, OpenAI or GitHub?

No. Headroom is an independent app made by Nio Martinez. It isn't made by, affiliated with or endorsed by Anthropic, OpenAI or GitHub.

Does it need my Claude login?

No. There is no Headroom account, and it never asks for your Claude login. Headroom reads files that Claude Code and the Claude desktop app already write on your Mac.

Does Headroom read my Codex login?

No. It reads Codex's session files and never opens its sign-in file.

Why does Copilot need a sign-in?

Copilot's usage is kept on GitHub, not on your Mac. Headroom uses its own read-only GitHub sign-in, only if you turn it on.

Can I see my company's Copilot seat?

Yes. If an organization pays for your Business or Enterprise seat, nothing is billed to you, so Headroom asks GitHub for that seat's monthly AI credits instead, with the same read-only sign-in, and shows them as a percent.

Does it send my data anywhere?

No. Headroom has no analytics, collects nothing and sends nothing to its developer. Claude and Codex work entirely from files on your Mac.

The one exception is opt-in: if you connect GitHub, Headroom asks GitHub for this month's Copilot usage, and talks to nothing else.

Which plans does it work with?

Claude: the 5-hour and weekly limits show for Pro and Max plans, and they cover chat, Cowork and Claude Code alike. Sessions and context bars show for anyone using Claude Code. If you use Claude Code in the terminal, click Connect terminal once, so Headroom can see those sessions and their limits too.

Codex: the weekly limit, as Codex records it while you use it. With an API key there are no limits to show.

Copilot: this month's usage. On a plan you pay for yourself, pick it in Settings to see a percent; a Business or Enterprise seat shows its monthly credits as a percent on its own.

How do I add the widgets?

Control-click the desktop and choose Edit Widgets, then search for Headroom. Limits shows the rings; Sessions shows what's running. Both come in Notification Center too.

Which Macs does it run on?

Any Mac with macOS 14 Sonoma or later.

Is it free?

Yes. Headroom is free, with no ads and no account.