How to check Codex token usage locally
Inspect Codex session token counts from local JSONL files and understand input, cached input, output, and reasoning without exposing your work.
Codex records token usage in local session files. Run npx tokenforest forest to read those files and see totals by model, project, day, and token class. The command works without an account and does not upload your prompts or code.
Check Codex usage in one command
npx tokenforest forest
Limit the report to a recent period with:
npx tokenforest forest --since 7
Or return structured data for a script or dashboard:
npx tokenforest forest --json
The JSON report includes totalTokens, weightedTokens, trees, token classes, events, sessions, projects, models, sources, daily totals, and scan diagnostics.
Where Codex session data lives
Codex stores sessions beneath ~/.codex/sessions by default. When CODEX_HOME is set, Tokenforest reads the sessions directory inside that location.
The scanner looks for Codex JSONL session files. It associates usage updates with the current session and model, then reduces them into one local report.
Why Codex usage updates need deduplication
A Codex session may write several token updates for the same conversation. Some records contain a cumulative total rather than a new amount to add.
Tokenforest identifies those records by their session context and usage data. It retains the latest usable total instead of summing every cumulative update. This avoids inflating a session merely because Codex wrote its running count more than once.
How Codex token classes are separated
The report uses these categories:
- Input tokens exclude cached input when Codex reports cached tokens inside the input total.
- Cache-read tokens record cached input separately.
- Output tokens exclude reasoning when Codex reports reasoning inside the output total.
- Thinking tokens contain the reported reasoning count.
- Cache-write tokens are included when present, though Codex session records may not report them.
Keeping the categories exclusive prevents cached input and reasoning from being counted twice.
Use raw counts for usage, weighted counts for tree progress
The local report shows both. Raw token counts describe the events found in your session files. Weighted tokens drive Tokenforest's progress rule:
input × 1 + output × 3 + cache write × 1.25 + cache read × 0.02 + thinking × 3
Every 50,000,000 weighted tokens advances the counter by one tree. This is a transparent funding threshold. It is not a claim that a fixed number of tokens always uses a fixed amount of electricity or produces a fixed amount of CO₂e.
Does the scan expose a private repository?
No repository name, file path, prompt, output, code, or tool argument is sent to Tokenforest. The terminal report is generated on your computer.
If you choose to connect an account, the sync payload contains usage counts, model names, source names, and timestamps. That is enough to maintain the forest without storing the work that produced the counts.
A reliable way to compare periods
Pick one date window and reuse it. For example, run npx tokenforest forest --since 30 at the end of each month and save the --json output. Compare raw token classes and weighted progress separately.
Do not treat tokens as a direct carbon meter. Hardware, runtime, data-centre conditions, power source, batching, and model implementation can change the energy used for the same token count. The token and carbon measurement guide explains the boundary.
If you also use Claude Code, read the Claude Code token usage guide. Its transcript format and duplicate rules are different.