Tracks your ChatGPT/Codex subscription limits using the login from the Codex CLI.
| Metric | Meaning |
|---|---|
| Session | 5-hour rolling window usage |
| Weekly | 7-day window usage |
| Spark / Spark Weekly | GPT-5.3-Codex-Spark model limits — a 5-hour and a weekly window. Shown only when your account has the limit (otherwise "No data"), and tucked below the "show more" caret by default |
| Rate Limit Resets | On-demand rate-limit reset credits, shown as a count (e.g. 2 available) with a colored dot for the soonest expiry; hover the value for a timeline of each credit's expiry |
| Extra Usage | Flex credits, shown verbatim as dollars + credits (e.g. $31.84 · 796 credits) |
| Today / Yesterday / Last 30 Days | Local spend, as cost, tokens, or both (see below) |
When Codex reports your plan name, OpenUsage shows it beside the provider name.
The usage entitlement self_serve_business_prolite displays as Business Premium.
This is a compatibility mapping for an observed entitlement; other Business/team plans keep their existing names.
If Codex reports only a 7-day window, it maps to Weekly without inventing a 5-hour Session meter.
Sign in once with the Codex CLI (codex); OpenUsage reads the same auth files ($CODEX_HOME respected) with a keychain fallback. Tokens refresh automatically and rotate back into the auth file.
Customize → Codex → Cost Estimates → Fallback Model optionally estimates usage that has no known price. The default is None. Choose a public model to use its rates for those estimates; known model prices and recorded costs remain unchanged. The existing unknown-model warning and tooltip remain visible when a fallback is used. Switching the choice recalculates local history without changing the model Codex runs. See model pricing for details.
Today / Yesterday / Last 30 Days are computed locally: OpenUsage reads the Codex CLI's session rollouts under ~/.codex/sessions/ and archived_sessions/ (or $CODEX_HOME) itself — no external tools needed. Symlinks are followed, so a Codex home linked into a synced location (say, a Dropbox folder) is read all the same. Codex usage from the pi coding agent counts too: OpenUsage reads pi's session logs under ~/.pi/agent/sessions/ (or $PI_CODING_AGENT_SESSION_DIR) and folds any Codex usage there into the same tiles and trend. The same applies when OpenCode uses its built-in ChatGPT Pro/Plus OAuth login: OpenUsage reads the openai rows from OpenCode's local database and attributes them to Codex. OpenCode API-key traffic is not included. Days are grouped in your Mac's local time zone, so they line up with your own calendar. Each period is one tile showing cost and tokens together ($4.08 · 1.2M tokens); a day with no usage reads No data rather than a misleading $0.00 · 0 tokens — the same as every other spend-tracking provider. The live Session and Weekly meters are unaffected. The dollars are estimated from token counts at API rates (that's the ⓘ) using the shared model pricing; sessions that ran on the fast/priority service tier — as recorded in each session's own log — use the fast rates for exactly those turns. Older logs without tier metadata, and everything else, price at standard rates; the current config.toml setting is not consulted, so flipping the tier never reprices past days. Auto-review usage keeps its codex-auto-review name in the model breakdown, while its cost uses the dated model fallback available for that event. The token counts themselves are measured. Subagent and forked sessions copy their parent session's token history into their own log; OpenUsage recognizes those copies and counts each token once, no matter how many subagents a session spawns. No log data leaves your Mac.
Large session files are read in small chunks instead of being loaded into memory. Unusually large individual records are skipped and logged; local spend can be incomplete if a skipped record contained usage.
For supported GPT-5.4, GPT-5.5, GPT-5.6, and GPT-6 models, requests above 272k input tokens use OpenAI's long-context rates for the whole request. These Codex-specific request rules apply consistently to native Codex logs and zero-cost Codex OAuth usage imported from pi or OpenCode. Daybreak Blue usage is priced as GPT-5.6 Sol, matching OpenAI's published alias and Daybreak pricing. Cached input uses the published cache-read discount when the pricing source provides one; otherwise it is estimated at the full input rate. Fast/priority estimates use each model's published Codex multiplier (for example, GPT-5.5 uses 2.5×); model names ending in -fast are normalized to their unscaled base rate before that multiplier is applied once.
- "Not logged in" — run
codexand sign in, then refresh. - API-key-only setups can't read subscription usage — sign in with your ChatGPT account instead.
- Spend tiles show "No data" — OpenUsage found no qualifying Codex usage in Codex, pi, or OpenCode logs from the last 30 days. If your Codex home lives somewhere custom, set
CODEX_HOMEso both the Codex CLI and OpenUsage look in the same place. - OpenCode usage is missing — OpenCode must currently have an
openaiOAuth credential in itsauth.json. An OpenAI API key is deliberately excluded from Codex subscription totals.
GET https://chatgpt.com/backend-api/wham/usage with the Codex OAuth token; refresh via auth.openai.com. A 401/403 triggers one token refresh and retry. Session and Weekly are classified by each usage window's duration rather than by its primary/secondary slot. This matters when Codex temporarily removes one limit and moves the remaining weekly window into the primary slot. Payloads without a recognized duration retain the primary-as-Session and secondary-as-Weekly compatibility fallback; response headers fill percentages missing from the corresponding window.
Spark and Spark Weekly come from the same response's additional_rate_limits array — model-specific limits that reuse the duration-based Session/Weekly classification. OpenUsage surfaces the entry whose name identifies GPT-5.3-Codex-Spark as those two meters; accounts without the limit simply omit the entry, so the rows read "No data". Other model limits in that array aren't shown.
OpenUsage preserves Codex's reported used_percent verbatim. If the API reports 1% used for an untouched window, the app shows 99% left; if it reports 0%, the app shows 100% left. Codex rows use the normal reset label rather than inferring a special "Not started" state. Burn-rate pacing still waits until enough of the window has elapsed — and until something has actually been used — to make a useful projection.
The "Rate Limit Resets" row shows the on-demand reset-credit count, e.g. 2 available, with a colored dot for the soonest credit's expiry — blue beyond a week, yellow within a week, red within 48 hours. OpenUsage also makes a best-effort GET https://chatgpt.com/backend-api/wham/rate-limit-reset-credits call — the dedicated endpoint that lists each credit's expiry — and surfaces those in a popover when you hover the value: a timeline of each reset, soonest-first — a numbered color dot, the exact expiry time (Jul 12 at 5:30 PM), and the countdown to it (12d 18h) on the trailing edge. When no credits are available it reads 0 available and the popover shows You have no rate limit resets. If the dedicated call fails, the row falls back to the count embedded in the usage body (rate_limit_reset_credits.available_count); since that body carries no per-credit expiries, the popover states the count (N available) and notes that expiry times are unavailable rather than implying there are none.
You can also spend a reset credit right from that popover — the same claim the Codex CLI's "Usage limit resets" picker performs. Hover a credit in the timeline and a Use button appears; clicking it expands that credit into an inline confirmation ("Immediately reset your usage limits. This can't be undone.") with Reset / Cancel. Confirming claims that exact credit and immediately resets your 5-hour and weekly windows; the app then refreshes Codex so the meters and the remaining count reflect it before the success line ("Reset claimed. Enjoy!") appears.
Safeguards, because a claim is irreversible:
- Claiming is always a deliberate two-click flow behind the hover popover — nothing is ever claimed automatically.
- Each claim targets one explicit credit (re-matched against a fresh credit list at claim time) and carries an idempotency key, so a retry after a network error can never spend a second credit.
- If the credit was meanwhile used elsewhere (CLI or web) the popover says it's no longer available and refreshes; if your usage doesn't need a reset, Codex refuses without spending the credit and the popover says so. After a claim resets usage, the remaining Use buttons disable ("nothing to reset") until the popover is reopened.