CodexTokenTracker

CodexTokenTracker is a local macOS menu bar utility for checking holistic Codex usage. It shows Codex rate-limit windows, reset times, remaining percentage, token stats, credits when available, and the last refresh time.

The app is intentionally status-first. It does not inspect conversation contents and does not read ~/.codex/auth.json directly.

Requirements

• macOS 14 or newer
• Swift 6 / Xcode command line tools
• Codex CLI installed and logged in

The app talks to Codex through:

codex app-server --listen stdio://

Codex app-server uses newline-delimited JSON-RPC messages with the JSON-RPC header omitted on the wire.

Build

Scripts/test.sh
swift build --disable-sandbox --cache-path .swiftpm-cache/cache --config-path .swiftpm-cache/config --security-path .swiftpm-cache/security
Scripts/build_app.sh

The build script creates:

dist/CodexTokenTracker.app

Open the app bundle or copy it to your preferred Applications folder.

Privacy

CodexTokenTracker asks Codex app-server for account, rate-limit, and exact /usage token stats. Daily and weekly token rows are anchored to the newest daily usage bucket returned by Codex, not the local wall-clock day, so they stay aligned with /usage when the server has not published a bucket for the current date yet. It reads local token_count events from Codex session JSONL files only as an estimated device fallback when exact usage is unavailable. It does not read or store Codex auth tokens, local SQLite databases, or prompt text. If app-server is unavailable, the app shows an explicit error instead of scraping local secrets.

Design

• Menu bar: minimal monochrome status icon with no numeric percentage text.
• Popover: returned limit buckets, reset times, credits, exact daily/weekly/cumulative usage stats, freshness, manual refresh, and Codex usage link.
• Refresh: on launch, on popover open, and from the refresh button. Data older than 60 seconds is marked stale.
• Startup: after it has been opened once, the app registers itself to start again at macOS login/restart. If Apple's login-item service is unavailable, it writes a user LaunchAgent fallback.