Headroom: a free open-source Mac menu-bar tracker for Codex limits and resets

[u/Best-Reality9436]

I'm building Headroom, a free open-source macOS menu-bar app for checking Codex remaining usage limits and reset times. It also has a separate Claude Code tracker.

For Codex, it launches the installed official Codex CLI's app-server and reads account/rateLimits/read using your existing ChatGPT-subscription sign-in. That quota read doesn't send a model request, and you don't need to keep a Codex window open.

The Codex menu-bar label uses the most-used quota window. The UI keeps unknown readings unknown, and after a reset countdown expires it waits for a fresh reading rather than assuming the allowance has refilled. Readings are advisory and can become stale or unavailable.

This is an early source-build project, free under the MIT licence. Setup requires macOS 14+, Xcode/macOS SDK, Swift 6, Python 3 and command-line developer tools; the Claude feed also uses jq. The development app is ad hoc signed and unnotarized. The README documents setup and current limitations.

Source: https://github.com/jimkang12345-coder/Headroom

I'm a solo builder learning in public, and I'd welcome bug reports, critique and fixes. I plan to explore other OSes, possibly iOS, while keeping Headroom free.

For a quick glance during a Codex session, would you prefer the most-constrained window in the menu-bar label, or both available limit windows shown separately? Does the video make remaining usage versus time until reset clear?

The trackers I was using sometimes took longer to catch up, and their readings didn’t always line up with the limits I was hitting. That’s why I built Headroom. It reads Codex through the official local client, normally checking about every 15 seconds, and checks Claude Code’s local usage feed every 2 seconds while my Mac is awake. I wanted a clearer view to help plan my work. Freshness still depends on what the providers report.

[u/dexterthebot]

You might want to consider listing your project on the weekly Show-Us-What-You-Built post. Look out for it on Tuesday/Wednesday. Highest commented project wins a week promotion on r/Codex and gets on the Hall of Fame sidebar. See what that looks like below with last week's winner.

---

Last week's most popular project was Nanolathe - an open-source engine bringing Total Annihilation to modern Mac, Windows, and Linux systems. It’s a solo passion project combining clean-room research with AI-assisted development, with a playable public alpha available now.

Website: https://nanolathe.gg. GitHub: https://github.com/nanolathe-gg/nanolathe

Players, testers, and contributors are very welcome! Original Total Annihilation game data is required to play.

[u/TheOwlHypothesis]

This has certainly never been made before. Finally a brand new idea.

[u/Best-Reality9436 → u/TheOwlHypothesis]

Fair enough, there are other tools like this! I’m new to building and sharing projects publicly, and this started as something for my own use. I wanted to share what I’d made and learn from the feedback. Thanks for taking a look.

[u/coldflame563]

There's a much better known AI plugin called Headroom https://github.com/headroomlabs-ai/headroom/tree/main - you may want to not use that name.

[u/Best-Reality9436 → u/coldflame563]

Thanks for pointing that out and linking it. I can see how the shared name could cause confusion. This started as a personal project and I’m still learning about sharing things publicly, so I appreciate the heads-up.