Quick answer
A Codex usage tracker reads the session files Codex writes to `~/.codex/sessions` and turns them into tokens per session, per model, and per day, alongside the current 5-hour and weekly windows. UsageAtlas does this locally, is free and open source, and needs no account.
What a Codex tracker can record
Codex already writes down more than the CLI shows. Every session produces a JSONL file containing the messages, the model, and token counts. A tracker turns that into answers you can act on.
| Field | Source | Why it matters |
|---|---|---|
| Session list | One JSONL file per session | Find the run that burned the window |
| Input tokens | Token count event per turn | Explains context growth |
| Cached input | Same event, separate field | Shows how much the prompt cache saved |
| Output and reasoning | Same event | The expensive half of a long agent run |
| Model | Session metadata | Compare cheap and strong models |
| Reset windows | Current limit state | Know when capacity returns |
Anything beyond these fields, such as a per-project dollar figure, is a calculation laid on top. That is fine as long as the app shows its inputs.
Point a tracker at Codex
- Install UsageAtlas for Windows, macOS, or Linux.
- Open the app and let detection find Codex, or set a custom
CODEX_HOMEif your sessions live elsewhere. - Open Today for the two windows and their reset countdowns.
- Open History to see daily tokens, and Insights for the model split.
- Turn on an alert at the remaining percentage that should warn you.
Nothing is uploaded by default. The app reads the folder on your machine, and cloud sync is opt-in. That matters if your sessions contain client code.
Where a tracker stops
Local files tell you what Codex recorded. They do not tell you how the provider will bill a cached token or how a promotional allowance is applied. Treat the tracker as a consumption record, not an invoice.
- Deleted session files disappear from history.
- Sessions started on another machine are not visible unless you copy the folder.
- A provider-side change to limits can lag behind the app's last refresh.
- Team billing lives in the provider console, not in local files.
For the per-session view, see Codex token usage. For the clock, see the Codex reset tracker.
Questions, answered
Does a Codex usage tracker need my OpenAI login?
No. Local trackers read the session files already on disk. A login is only needed if you connect a provider account for reported quotas or cloud sync.
Can I track Codex usage on a team?
Only machine by machine, because sessions are local. For organization-wide numbers you need the provider's admin reporting, or each developer running a tracker and sharing exports.
How far back does Codex session history go?
As far back as the files you keep. Codex does not delete old sessions on a schedule, but cleanup tools and reinstalls can. Back up ~/.codex/sessions if the history matters.