macOS menu bar usage meter for OpenAI Codex.
Codex-Usage reads local Codex session logs from ~/.codex and keeps remaining
5-hour and weekly quota visible directly in the menu bar. You do not need to
click the menu bar item to see the numbers. It is local-only and does not read
Codex auth tokens.
Unzip it, then open Codex-Usage.app. If macOS blocks the first launch, right-click the app and choose Open.
The menu bar item is two compact circular gauges. The number inside each ring is remaining quota:
(79) (96)
Left: 5-hour window. Right: weekly window.
Clicking the item opens a compact menu:
5h · 79% · reset 2h
1w · 96% · reset 6d
Launch at Login
Refresh
Quit Codex-Usage
Codex-Usage reads only known local Codex usage logs:
~/.codex/sessions/**/*.jsonl
~/.codex/archived_sessions/*.jsonl
It looks for event_msg entries where payload.type == "token_count" and reads
payload.rate_limits.primary and payload.rate_limits.secondary.
It does not read ~/.codex/auth.json.
Requirements:
- macOS 13+
- Xcode command line tools
- OpenAI Codex app or CLI already used on this Mac
Build and open the app:
git clone https://github.com/theconomicat/Codex-Usage.git
cd Codex-Usage
./Scripts/package_app.sh
open ./Codex-Usage.appTo keep it installed, move Codex-Usage.app to /Applications.
Pushing a version tag builds the app on GitHub Actions and uploads
Codex-Usage-macos.zip to a GitHub Release automatically.
git tag v0.1.0
git push origin v0.1.0To build the same zip locally:
./Scripts/package_app.sh
ditto -c -k --norsrc --keepParent Codex-Usage.app Codex-Usage-macos.zipPrint the latest local usage without opening the menu bar app:
swift run CodexUsage -- --printRun tests:
swift testBuild an app bundle:
./Scripts/package_app.sh
open ./Codex-Usage.appThe Codex local JSONL format is not a public API, so this project treats parsing as best-effort and keeps the reader small and easy to update.
If a reset time passes before Codex writes a fresh log entry, Codex-Usage resets that window locally instead of showing stale usage.
MIT