codex-usage is a local, cross-platform command-line monitor for the usage associated with the currently logged-in OpenAI Codex CLI account. It is intentionally a reusable core for menu-bar, tray, status-bar, and automation integrations—not a desktop UI.
It is written in Go for small standalone macOS and Windows binaries with no runtime dependencies. It locates codex on PATH, starts codex app-server, completes the documented initialize / initialized handshake, and requests account/rateLimits/read. Codex manages authentication throughout: this project never reads ~/.codex/auth.json, never prints tokens, and sends no telemetry or usage data off-device.
Install and log in to the Codex CLI normally, then:
go build -o codex-usage ./cmd/codex-usage
./codex-usage
./codex-usage --json
./codex-usage check
./codex-usage watch --json-linesOn Windows use go build -o codex-usage.exe ./cmd/codex-usage and run codex-usage.exe. The codex executable must be available on PATH on both platforms.
The minimal native SwiftUI wrapper in macos/CodexUsageMenuBar starts one persistent codex-usage watch --json-lines process and renders its snapshots in a MenuBarExtra. It is deliberately small and has no network or auth access of its own.
cd macos/CodexUsageMenuBar
swift runEnsure the built codex-usage executable is on the GUI process's PATH (or update the wrapper's launch command). It displays remaining monthly percentage, monthly/weekly use, reset dates, and a manual monitor restart action.
One-shot commands start an app-server instance, query it, then close it cleanly. watch keeps a single connection open. It reads an initial snapshot, reacts immediately to account/rateLimits/updated notifications when emitted, and uses a 10-minute fallback poll (configurable with --interval; minimum one minute). If the server exits or a machine wakes without a valid connection, it reconnects with a bounded 1–60 second exponential backoff.
--json returns a stable normalized schema with null for unavailable server fields:
{"monthly":{"used_credits":960.85,"limit_credits":2000,"remaining_percent":52,"resets_at":"2026-09-01T00:00:00Z"},"rolling_limit":{"used_percent":0,"window_minutes":10080,"resets_at":"2026-08-24T00:00:00Z"},"daily":{"used_tokens":null,"limit_tokens":null,"used_percent":null,"resets_at":null},"spend_control_reached":false,"plan_type":"team","fetched_at":"2026-08-17T12:00:00Z","velocity":{"credits_since_last_check":null,"credits_last_hour":null,"credits_per_hour":null,"percentage_point_increase":null}}account/usage/read is requested opportunistically. Its format differs between Codex versions, so only recognizable token fields are populated; unavailable data stays null.
watch --json-lines emits snapshot, warning, and error events. Warnings are emitted only when a severity changes; clearing a condition allows a future crossing to alert again. Defaults are warning/high/critical at 60/80/90% monthly use and a 300-credit/hour spike; use the matching flags to change them. check exits 0 normally, 1 for warning/high, and 2 for critical/spike.
codex-usage diagnostics reports the discovered Codex executable/version and the active monitor strategy without querying account data.
Local state is stored with user-only permissions in the normal application-data directory (~/Library/Application Support/codex-usage on macOS and %AppData%\\codex-usage on Windows). It contains recent numeric observations and alert state only, used to calculate credits since last check and credits in the prior hour.
gofmt -w .
go test ./...
go vet ./...Tests include a captured/synthetic Business rate-limit response, missing plan-specific limits, and an unrelated notification arriving between a request and its response. GitHub Actions validates macOS and Windows and builds tagged-release artifacts for Apple Silicon, Intel macOS, and Windows AMD64.
For a tagged release, GitHub Actions also writes a SHA256SUMS.txt file alongside the three binary artifacts.