If you're running Codex sessions regularly, you already know what it's like to hit a limit mid-task. WhatsLeft puts the gauge on your deck so you're never caught off guard. No sign-in, no account to configure — it reads the same file the Codex CLI already wrote.
Seven actions, one plugin
Session
Your 5-hour rolling usage window.
Weekly
Your 7-day rolling window.
Overview
Both session and weekly on one key.
Status
Live Codex CLI service status — green, degraded, or outage at a glance.
API Credits
Your OpenAI API spending this month. Set a budget to track remaining balance.
Velocity
Session sparkline or daily-peaks bar chart. See how fast you're burning quota.
Trend
Mon–Sun heatmap of average session peaks. Spot your heavy-usage days at a glance.
What it does
- Four display modes — Gauge (arc), Bar (horizontal fill), Solid (full-key color), or Vertical bar (side column with large % readout). Switch per key from the Property Inspector.
- Burn indicator — three graduated signal bars that show how fast you're consuming Codex quota right now. One orange bar = low rate, two = moderate, three red bars = high. Toggle per key in Property Inspector → Burn intensity. Works across all four display modes.
- Color-coded gauge — purple means healthy, red means under 20% remaining. The color tells you what you need to know before you read a number.
- Reads from
~/.codex/auth.json— no separate sign-in inside the plugin. It uses the credentials the Codex CLI already stored. - All three actions share one connection — connect once from any key's Property Inspector, done for all.
- Tap to open usage page — opens chatgpt.com/codex/cloud/settings/usage in your browser.
- Hold to refresh — skips the polling interval and fetches immediately.
- API Credits tracker — connect an OpenAI Admin API key to see your monthly spend on a dedicated key. Optionally enter a budget to show remaining balance instead. Turns red below 20%.
Who it's for
Engineers using Codex for code tasks
When you're in the middle of an agentic Codex run, knowing you're at 12% session means you decide whether to finish the task or split it — not lose the context when it cuts out.
Anyone running Codex in agentic mode
Agentic tasks burn tokens fast. The weekly gauge gives you a horizon — how much is left before the window resets.
Getting set up
- Install the Codex CLI and run
codexonce in your terminal to log in. This writes~/.codex/auth.json. - Install WhatsLeft from the Marketplace and drag whichever actions you want onto your keys.
- Open any key's Property Inspector → Connect to Codex. Configure once; all three usage actions share the connection.
- Optional — API Credits: drag the API Credits action onto a key, paste an OpenAI Admin API key (
sk-admin-*) from platform.openai.com → Admin Keys, and click Connect.
Good to know
Key shows "Setup needed"
Codex isn't installed or not logged in. Run codex in your terminal to complete login, then click Connect to Codex in the Property Inspector.
Plugin shows nothing after login
The auth.json file must contain both tokens.access_token and tokens.account_id. If either is missing, sign out of Codex and log in again by running codex in your terminal.
My auth.json is in a non-default location
Open the Property Inspector → Advanced settings, and set a custom path to your auth.json file.
"Token expired"
Run codex in your terminal to refresh. The plugin picks up the new token on its next poll. If it doesn't, click Connect to Codex again or use Reset auth from the Property Inspector.
API Credits: how do I connect?
Drag the API Credits action onto a key, open its Property Inspector, and paste an OpenAI Admin API key (starts with sk-admin-). Create one at platform.openai.com → Admin Keys. Click Connect. The key shows your spending for the current month. Hold the key for 600ms to force a refresh. You must be an org owner to create admin keys.
API Credits: shows "OK / key valid" but no dollar amount
You connected a project key (sk-proj-*). Only Admin API keys (sk-admin-*) can access the spending endpoint. Go to platform.openai.com → Admin Keys, create an admin key, disconnect, and reconnect.
API Credits: how does "remaining balance" work?
OpenAI doesn't expose a credit balance endpoint via API. The plugin shows spending instead. To see how much you have left, enter your total credits in the Budget field in the Property Inspector — the key then shows remaining = budget − spent and turns red when below 20%. Update the budget field whenever you top up.
What do Velocity and Trend show?
Velocity shows how you've been consuming Codex quota over time. In Session mode it draws a sparkline of utilization readings across your current session, with an "avg X% used" label. In Weekly mode it shows a bar chart of daily peak readings over the past 30 days. Switch between the two from the action's Property Inspector. Tap to open the Codex usage page, hold to force a refresh.
Velocity/Trend says "gathering data…"
Both actions build their charts from history that accumulates in the background — stored at ~/.config/microdash/whatsleft-history.json. Session Velocity needs at least two readings within the current session window (roughly 30 seconds apart). Weekly Velocity and Trend need daily records; give it a few days to fill in. No configuration needed — once you're connected, data collects automatically.
What is the burn indicator?
An optional widget showing three graduated signal bars in the corner of the key — like mobile signal strength, but for usage rate. One orange bar means you're burning slowly, two means a moderate rate, all three red means high burn. Enable it per key via Property Inspector → Burn intensity toggle. It's available on Session, Weekly, and Overview in all four display modes (Gauge, Bar, Solid, Vertical bar). The rate is calculated from your last four usage readings.