Skip to content

About

Monitor Codex usage, 5-hour & weekly limits, reset times, and credits — right from your macOS menu bar.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Repository files navigation

CodexMenuBar logo

CodexMenuBar

A native macOS menu bar app for monitoring your OpenAI Codex usage limits at a glance.

CI status Release workflow Latest release GitHub downloads License

CodexMenuBar showing 5-hour and weekly Codex usage from the macOS menu bar
Example with the percentage display set to Used.

Status: Available as a Homebrew Cask and as downloadable builds from GitHub Releases.

Why CodexMenuBar?

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 window
  • W73% — remaining quota in the weekly window
  • 240 — 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.

Features

  • 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

Requirements

  • macOS 13 Ventura or newer
  • Codex CLI installed and authenticated
  • Xcode / Swift 5.9 or newer for development

Install

Homebrew — recommended

Install CodexMenuBar directly from the official project tap:

brew install --cask sangimed/tap/codex-menubar

Alternatively, add the tap first:

brew tap sangimed/tap
brew install --cask codex-menubar

Upgrade to the latest stable release with:

brew update
brew upgrade --cask codex-menubar

CodexMenuBar 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.

GitHub Release

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.

Build from source

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 package

make 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.

How it works

CodexMenuBar talks to the locally installed Codex CLI through the Codex app server:

codex app-server --stdio

The 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:

  • 300 minutes → 5-hour window
  • 10080 minutes → 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.

Local state

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.

Packaging

make app
make package

make 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.

GitHub Releases and Homebrew

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.3

For 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-menubar

Prereleases 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.

Privacy

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.

Architecture

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.

Development

Common commands:

make check
make build
make test
make run

The 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.

Highlights

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 .app and 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

Known limitations

  • 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-server process 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.

Contributing

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.

License

CodexMenuBar is released under the MIT License.

Disclaimer

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.

About

Monitor Codex usage, 5-hour & weekly limits, reset times, and credits — right from your macOS menu bar.

Topics

Resources

Contributing

Security policy

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages