How does Usage HUD know my Codex 5-hour and weekly usage?

It reads the rate_limits events Codex CLI writes to its local session logs. Each event carries a used percentage, a reset timestamp, and a window length; 300 minutes is the 5-hour window and 10080 minutes is the weekly window.

Is the Codex number official?

No. It is parsed from local Codex rate-limit events, and the HUD labels it high confidence with that exact caveat. It is not a billing API.

Should I use CodexBar instead?

If Codex is the only tool you meter and CodexBar already works for you, yes. Usage HUD is for several providers in one menu bar with a confidence label on each number.

Codex CLI usage limit

Codex CLI usage limit: the 5-hour and weekly windows on a Mac

Codex CLI meters a subscription with two windows: a short one and a weekly one. The CLI tells you when you are close, and by then the choice is made for you. Usage HUD is a free Mac menu-bar meter that reads the rate-limit events Codex already writes to its local session logs and shows both windows, with reset times, before you get there.

Read this first: CodexBar is free, MIT-licensed, and tracks Codex well. If Codex is the only tool you meter and CodexBar already works for you, you do not need Usage HUD. Usage HUD is for people who also run Claude, Gemini, Grok, or Ollama and want one meter with a confidence label on every number.

Where the numbers come from

Codex CLI keeps session logs as JSONL files under ~/.codex/sessions. Among the events in those logs are rate_limits events carrying a primary window and a secondary window. Each window has a used percentage, a reset timestamp, and a window length in minutes. Usage HUD reads the newest of those events. A window of 300 minutes is shown as the 5h window; a window of 10080 minutes is shown as the Weekly window.

This is local telemetry, not a billing API. The HUD labels the Codex reading measured, with the note “Parsed from local Codex rate-limit events; this is not an official billing API.” That label sits next to the number so it is never mistaken for a provider-reported figure.

What the menu bar shows

One bar for Codex next to the bars for your other providers. Click it and the panel lists the 5-hour window and the weekly window, each with its percentage used, the reset time from the event, the time the reading was captured, and the confidence label. When a window passes its reset time, the HUD drops that reading as expired rather than showing a stale percentage as if it were current.

Because the source is the session log, the reading only changes when Codex emits a new rate-limit event, which happens while you use Codex. If you have not run Codex today, the freshness stamp says so.

When the number looks wrong

Run codex-usage-doctor. It checks the state directory permissions, whether the Codex session logs are visible, the newest parseable rate-limit event and its age, the freshness and confidence of the current Codex snapshot, and whether the HUD and its background writers are loaded. It prints none of your prompts, messages, or secrets. If the doctor says no rate-limit event was found, the meter has nothing to show yet, and it says so instead of drawing a bar.

Get Usage HUD

Free · no account · signed and notarized by Apple

Download for Mac

The download is a notarized disk image. Drag Usage HUD to Applications, open it, then click Set up.

Your Mac: macOS 14 or later, Apple silicon or Intel.
Claude and Codex: Claude Code or Codex signed in. Nothing else to install for those two lanes.
Gemini and Grok: those lanes need Node.js 18 or later.
Local models: the local lane reads your Ollama logs.

Tips are optional and go through Stripe. Free first: claude-usage-check shows which number is official. If CodexBar already works for you, you may not need this.

Codex CLI usage meter for the Mac menu bar · Usage HUD vs CodexBar · Claude Code usage limit reached · Usage HUD home