A Codex CLI usage tracker in the MacBook notch
Notchmeter shows Codex's session, weekly or monthly rate-limit windows beside the notch, from the same backend Codex itself asks, each with a pace tick, a projection and its reset; prices this Mac's Codex sessions at OpenAI's published rates; lists the Codex sessions running in a terminal, each marked as found without the hook; and, with the optional hook, counts your running threads, shows their waits and finished turns as they happen, and lets you approve a Codex request from the notch. It reads the login Codex already keeps and never refreshes or stores it.
macOS 15 or later · Apple silicon or Intel · no account, ever
What Notchmeter shows for Codex
The render on the right has Codex on a free plan, its Session with no data and its Monthly window untouched; a paid plan fills the same meters.
- The windows your plan has: Session (5 hours), Weekly, or Monthly, named by the length the backend declares, with the used share, a pace tick, a projection and the reset as a countdown or an exact time, and the plan's name on the card.
- Offline: the newest
rate_limitssnapshot Codex wrote into its own session rollouts, tagged snapshot and noted “Reset since Codex last reported” once its reset has passed, because a figure from disk may be stale. - Reset credits, opt-in: shown, with when each expires, and never claimed.
- Cost: this Mac's Codex sessions priced at OpenAI's published rates, today, yesterday, the week, the month, 30 and 90 days, by model and by folder, with a burn line when the last hour ran hot.
- Sessions: every Codex session running in a terminal, listed without the hook and marked as found without it. With the hook, every running thread and its live state: a dot on the ring while Codex waits for an approval, each finished turn and a refresh the moment it ends, and Allow or Deny from the notch.
Where each figure comes from
The windows are OpenAI's own figures; the cost is an estimate whose rule is written down.
| Figure | Source | Notes |
|---|---|---|
| Session, Weekly, Monthly | GET https://chatgpt.com/backend-api/wham/usage, the backend Codex itself asks, on a five-minute cadence | Undocumented. The request carries Codex's token as Authorization: Bearer, User-Agent: Notchmeter/<version>, and ChatGPT-Account-Id when auth.json holds one. |
| The same, offline | The newest rate_limits line in ~/.codex/sessions/**/*.jsonl | Tagged snapshot; a weekly-only or monthly plan fills the primary slot by its declared length, as the backend read does. |
| Reset credits | GET …/wham/rate-limit-reset-credits, opt-in | Shown and never claimed. |
| Cost | This Mac's rollouts under $CODEX_HOME/sessions: one token_usage_record per response, fresh input as input_tokens less cached_input_tokens, reasoning already inside output_tokens, priced at OpenAI's standard-tier rates read 2026-09-02 | Cache writes are billed only on the GPT-5.6 rows, the long-context tier above 272K input tokens where a model publishes one, and a model with no published rate is named under “Unpriced” rather than valued at $0. A replayed response_id is counted once. |
| Sessions, waits | The optional hook: Codex's PermissionRequest is a documented wait; Stop has no failure kind. Without it, the Codex sessions running in a terminal, each marked as found without the hook | A limit hit waits for the next poll of the meter, because no Codex event fires for one; nothing is claimed that a documented signal does not prove. |
The login comes from auth.json in $CODEX_HOME, else ~/.config/codex, else ~/.codex: the token is read and never refreshed or written, and a setup on an API key alone has no plan windows, which the card says. The plan's name is read from Codex's own plan_type.
The cost is the API-equivalent value of the work at list price. A ChatGPT Plus, Pro or Business plan includes Codex in the subscription, so on those plans nothing here is a bill; on an API key it is an estimate at the standard tier, since a rollout does not record whether a turn ran under Batch, Flex, Priority or Fast mode. The rates, the four gaps and the golden tests are in Codex sessions.
What it says to do about it
The Advice strip's lines for Codex, each worded as an instruction.
Questions
Which Codex plans does it meter?
Any ChatGPT login Codex has made with codex login. The windows are whatever the backend returns for that plan, session, weekly or monthly, named by the length each declares, and the plan's name is shown on the card. A setup on an API key alone has no plan windows, and the card says so.
Does it work offline, or when the endpoint fails?
Yes. It falls back to the newest rate_limits snapshot Codex wrote into its own session rollouts, tagged “snapshot” so a figure from disk is never mistaken for a live one, and noted “Reset since Codex last reported” once that snapshot's reset has passed.
Is the Codex cost my bill?
No. It is the API-equivalent value of the work at OpenAI's list price, computed from this Mac's rollouts. A ChatGPT Plus, Pro or Business plan includes Codex, so on those plans it is a measure of pace and of what the plan is worth; on an API key it is an estimate at the standard tier. What is not priced is named on the card rather than counted as $0; the rules are in docs/accuracy.md.
What are reset credits, and does Notchmeter use them?
Codex can grant credits that reset a window early. With the opt-in read on, Notchmeter shows them and when they expire, and the Advice strip says so when one expires within a day while a window is behind pace. It never claims one; that is done in Codex.
Can I approve a Codex request from the notch?
Yes, with the hook. Codex's PermissionRequest documents the same decision shape as Claude Code's, so the panel opens on the request with Allow and Deny, and everything about it fails open: hand it back, let the hold run out, or quit Notchmeter, and Codex asks in the terminal exactly as it always has. Codex never reports the answer, so the waiting mark clears at the thread's next event or after ten minutes. docs/hooks.md has what the hook sends.
Does it need my OpenAI login?
No. It reads the auth.json Codex keeps, never refreshes or writes it, and sends the token only to chatgpt.com in the same read-only usage request Codex itself makes. Sign into a different account in Codex and the notch follows.
Install it
macOS 15 Sequoia or later, Apple silicon or Intel. Signed, notarised, and it updates itself. Free forever, MIT licensed.
Notchmeter is a Mac app. There is no Windows or Linux version; if you want a Windows one, the Windows issue is where to say so. How every figure is built, with its source and its date: docs/accuracy.md.