A native macOS menu bar app for monitoring your OpenAI Codex usage limits at a glance.
Example with the percentage display set to Used.
Status: Available as a Homebrew Cask and as downloadable builds from GitHub Releases.
Codex exposes usage limits for its rolling 5-hour window and weekly window, but checking them manually interrupts your workflow.
CodexMenuBar keeps that information directly in the macOS menu bar with a lightweight native UI and no separate backend.
The menu bar shows a compact summary such as:
13% · W73% · 240
With the default Remaining percentage mode:
13%— remaining quota in the rolling 5-hour windowW73%— remaining quota in the weekly window240— available Codex credits, shown only when Show credits in menu bar is enabled and Codex reports a balance∞— unlimited credits when Codex reports them as unlimited
Switching the percentage preference to Used makes the 5-hour and weekly values represent quota used instead. Credits remain a balance and do not change with percentage mode.
Click the item to see detailed five-hour and weekly usage, reset times, plan, credits, and refresh status.
- Native macOS menu bar app
- Connect to
codex app-server --stdio - Display 5-hour usage
- Display weekly usage
- Display reset countdowns
- Display available credits when reported by Codex
- Optional compact credit balance in the menu bar
- Manual refresh
- Live updates from
account/rateLimits/updated - Persistent local app-server session
- Configurable fallback resync (30 seconds by default)
- Preserve the last successful snapshot when a refresh fails
- Handle missing quota windows gracefully
- Apple Silicon and Intel-compatible Swift source
- Core response-model tests
- macOS GitHub Actions build and test workflow
- macOS 13 Ventura or newer
- Codex CLI installed and authenticated
- Xcode / Swift 5.9 or newer for development
Install CodexMenuBar directly from the official project tap:
brew install --cask sangimed/tap/codex-menubarAlternatively, add the tap first:
brew tap sangimed/tap
brew install --cask codex-menubarUpgrade to the latest stable release with:
brew update
brew upgrade --cask codex-menubarCodexMenuBar community builds are ad-hoc signed and are not notarized by Apple. macOS may therefore block the first launch. If that happens, try to open CodexMenuBar once, then go to System Settings → Privacy & Security → Open Anyway.
You can also download the latest macOS ZIP from the repository's GitHub Releases page, extract it, and move CodexMenuBar.app to /Applications.
Release builds are universal and support both Apple Silicon and Intel Macs.
For development, or if you prefer to build CodexMenuBar yourself:
git clone https://github.com/sangimed/codex-menubar.git
cd codex-menubar
make check
make run
# Build an ad-hoc signed local app bundle
make app
# Build the app and a distributable ZIP
make packagemake run is intended for development. Features that rely on a real macOS app bundle, such as notifications and launch at login, should be tested with make app or an installed release.
CodexMenuBar has no normal application window and no Dock icon. Look for it on the right side of your macOS menu bar.
If this is your first Swift project, follow the complete setup guide in CONTRIBUTING.md. It covers installing Xcode, Swift, Codex, cloning the project, running it from Terminal or Xcode, tests, debugging, and common setup issues.
CodexMenuBar talks to the locally installed Codex CLI through the Codex app server:
codex app-server --stdioThe app performs the JSON-RPC initialization handshake once, keeps that local process alive, and requests an initial snapshot with:
account/rateLimits/read
A typical response contains:
{
"primary": {
"usedPercent": 82,
"windowDurationMins": 300,
"resetsAt": 1788125155
},
"secondary": {
"usedPercent": 26,
"windowDurationMins": 10080,
"resetsAt": 1788693894
}
}CodexMenuBar prefers the rateLimitsByLimitId.codex bucket when Codex exposes it, then falls back to the top-level rateLimits snapshot.
It identifies quota windows by duration instead of assuming that primary or secondary has a fixed meaning:
300minutes → 5-hour window10080minutes → weekly window
If Codex does not report one of those windows, the popover shows it as unavailable rather than fabricating a value.
If Codex exposes additional entries in rateLimitsByLimitId, CodexMenuBar surfaces them under Additional Codex limits using the server-provided limitName when available. CodexMenuBar does not guess which model a limit belongs to.
After the initial snapshot, CodexMenuBar listens for account/rateLimits/updated notifications and updates the UI immediately. Manual refreshes reuse the same connection, and a lightweight account/rateLimits/read runs at a configurable 15–300 second interval (30 seconds by default) as a fallback resync. If the app-server exits, CodexMenuBar restarts it with exponential backoff.
Preferences use macOS UserDefaults. Usage history is stored locally under Application Support and retained for seven days. Threshold notifications use the macOS notification center. No history is uploaded by CodexMenuBar.
make app
make packagemake app creates an ad-hoc signed universal dist/CodexMenuBar.app (arm64 + x86_64). The macOS .icns app icon is generated automatically from assets/codex-menubar-logo.svg and embedded in the bundle. Set CODESIGN_IDENTITY to use a Developer ID identity instead. make package additionally creates a versioned ZIP and SHA-256 checksum.
Launch at login and macOS notifications are intended for a packaged app build; swift run remains the development path.
The release workflow publishes versioned builds from main. The version
entered in Actions → Release → Run workflow is injected directly into the
app bundle, ZIP name, GitHub Release, and Homebrew Cask.
Tag-based releases are also supported:
git tag v0.2.3
git push origin v0.2.3For ordinary local builds, the bundle uses the neutral development version
0.0.0. You can simulate a versioned package locally with
VERSION=0.2.3 make package.
Release assets include the universal ZIP, its SHA-256 checksum, and a generated Homebrew Cask. Stable releases automatically update the sangimed/homebrew-tap repository, which powers:
brew install --cask sangimed/tap/codex-menubarPrereleases are published on GitHub but are intentionally not promoted through the Homebrew tap.
See RELEASING.md for the release workflow, Homebrew tap details, Gatekeeper notes, and stable/prerelease flow. Release highlights are tracked in CHANGELOG.md.
CodexMenuBar runs locally on your Mac.
It does not require a separate API key or hosted backend. It uses the locally authenticated Codex CLI session and does not read or copy ~/.codex/auth.json.
SwiftUI / MenuBarExtra
│
▼
UsageStore
│
▼
CodexAppServerClient
│
▼
codex app-server --stdio
│
├── account/rateLimits/read
└── account/rateLimits/updated
The repository is split into two Swift targets:
- CodexMenuBar — SwiftUI/AppKit menu bar UI and application state
- CodexMenuBarCore — Codex process management, JSON-RPC integration, models, and quota classification
Keeping protocol code outside the UI makes it testable without launching the menu bar app.
Common commands:
make check
make build
make test
make runThe project intentionally uses Swift Package Manager instead of committing an Xcode project file. Xcode can open the repository directly:
xed .See CONTRIBUTING.md for the complete beginner-friendly development setup and contribution workflow.
CodexMenuBar currently includes:
- Configurable menu bar display: both windows, 5-hour only, weekly only, or icon only
- Used vs. remaining percentage mode
- Configurable low-quota notifications
- Launch at login for packaged app builds
- Local
.appand ZIP packaging scripts - Seven-day local usage history
- Additional named/model-specific limit buckets when Codex exposes them through
rateLimitsByLimitId - Configurable background refresh interval from 15 to 300 seconds (30 seconds by default)
- Optional credit balance in the menu bar without extra label text
- Community releases are ad-hoc signed and are not Apple-notarized, so Gatekeeper may require explicit user approval on first launch.
- CodexMenuBar keeps one local
codex app-serverprocess alive while the app is running and reconnects automatically if it exits. - The Codex app-server protocol can evolve between Codex CLI releases.
- Some accounts may temporarily receive only one quota window from Codex.
Contributions are welcome. Start with CONTRIBUTING.md, especially if you have never configured Swift development on macOS before.
Security reports should follow SECURITY.md rather than being opened as public issues.
CodexMenuBar is released under the MIT License.
CodexMenuBar is an independent community project and is not affiliated with or endorsed by OpenAI.
Codex and the Codex app-server protocol may evolve over time, so compatibility can change between Codex CLI releases.