Your Codex usage limits, in the macOS menu bar, in your timezone.
-blue){kind=icon}
CodexBar shows your Codex plan limits in the menu bar. The menu-bar item shows the highest usage percentage; the dropdown lists each limit with a progress bar, its reset time in your local timezone, and whether you're ahead of a steady pace through the window.
You can also turn on local telemetry to keep a history of your usage limits, reset credits, and the tokens Codex uses on your Mac, in the format Bar UI reads.
Looking for the same simple menu bar experience for Claude? See ClaudeBar.
brew install --cask gordonbeeming/tap/codex-bar
open -a CodexBarCodexBar needs macOS 15 or later on Apple Silicon, plus the Codex CLI installed and signed in with ChatGPT.
The app launches at login by default. You can turn that off in Settings.
make install
open ~/Applications/CodexBar.appmake install builds a release binary and signs it with an available Apple Development identity, falling back to ad-hoc signing.
Open Settings… from the dropdown:
- Usage colours — use the default 75% warning and 90% critical levels, or drag the two splitters to choose your own.
- Pace flame — show a flame beside the menu-bar percentage when usage is ahead of a steady pace through a window.
- ⛽ Fuel tank mode — flip every percentage and bar from used to remaining. Instead of a limit filling from 0 → 100% as you burn through it, it starts full and drains toward empty like a fuel gauge. It's purely cosmetic: colours, the pace flame, and the steady-pace marker still track real usage, so a nearly-empty tank still turns red.
- Celebrations — choose full-screen reactions for session resets, weekly resets, and crossing the weekly pace line, or turn them off individually.
- Telemetry — off by default. Record OTLP JSON to
~/Library/Application Support/CodexBar/Telemetry, choose another folder, or open it in Finder. Capture every five minutes and retain 90 days by default; both are configurable.codexbar://telemetrylinks can change these after you confirm. See the telemetry format and coverage. - Launch at login — on by default for an installed app.
CodexBar starts codex app-server locally and reads its account/read and account/rateLimits/read responses once a minute, plus when the menu opens with stale data. Codex remains responsible for authentication and token refresh; CodexBar never reads ~/.codex/auth.json.
The app guards against temporary usage regressions before updating the display or firing a reset celebration. A suspicious drop must persist across three readings, while a real window reset or a Codex plan change is accepted immediately. Plan changes also reseed the celebration baseline, so upgrading doesn't create a fake reset signal.
If Codex isn't on the app's inherited PATH, CodexBar checks common Homebrew, fnm, Volta, nvm, and ~/.local/bin locations. Set CODEX_PATH to an explicit executable path if your installation lives somewhere else.
make run # Run directly from source
make test # Build and run the unit testsThe testable usage mapping, formatting, thresholds, celebration detection, and snapshot stabilization live in CodexBarCore. The app target is a small SwiftUI MenuBarExtra on top.
Publish a GitHub release tagged vX.Y and CI handles the rest: tests, Developer ID signing, notarization, stapling, DMG upload, and the signed Homebrew cask update.
For local setup, packaging details, CI secrets, and the full release process, see the development and release guide.
CodexBar is released under the MIT License.
The MIT license doesn't cover the OpenAI logo used for the menu bar icon (openAIKnotTemplateBase64 in Sources/CodexBar/MenuBarIconRenderer.swift). OpenAI owns that logo and it stays under OpenAI's brand guidelines. If you fork or redistribute CodexBar, you'll need your own rights to use it or a replacement icon.