ccusage turns local coding-agent logs into usage reports. It is useful when you want a history of Codex token consumption or JSON for further analysis. For remaining subscription allowance, use your client's account information: a log-based estimate answers a different question.
Start with a small, shareable dataset. It demonstrates a common counting mistake: cumulative readings of 1,200 and 1,800 represent 1,800 tokens in total, rather than 3,000.
Install a pinned local CLI
Open PowerShell in an empty directory with Node.js and Codex CLI installed. We used Node 24 and ccusage 20.0.51:
node --version
npm.cmd install --no-audit --no-fund ccusage@20.0.51
node .\node_modules\ccusage\src\cli.js --version
Calling npm.cmd avoids PowerShell selecting an npm .ps1 blocked by execution policy. ccusage is a CLI; this workflow needs no MCP registration.
Save this as make-sample.cjs:
const fs = require('node:fs');
const dir = 'usage-records/sessions/2026/11/16';
fs.mkdirSync(dir, { recursive: true });
const rows = [{ timestamp: '2026-11-16T08:00:00Z', type: 'turn_context',
payload: { model: 'gpt-5.2-codex' } }];
const usage = (input, cached, output) => ({ input_tokens: input,
cached_input_tokens: cached, output_tokens: output,
reasoning_output_tokens: 0, total_tokens: input + output });
rows.push({ timestamp: '2026-11-16T08:01:00Z', type: 'event_msg',
payload: { type: 'token_count', info: { model: 'gpt-5.2-codex',
total_token_usage: usage(1000,100,200), last_token_usage: usage(1000,100,200) } } });
rows.push({ timestamp: '2026-11-16T08:02:00Z', type: 'event_msg',
payload: { type: 'token_count', info: { model: 'gpt-5.2-codex',
total_token_usage: usage(1500,150,300), last_token_usage: usage(500,50,100) } } });
fs.writeFileSync(`${dir}/usage.jsonl`, rows.map(x => JSON.stringify(x)).join('\n')+'\n');
Create the records and run your first report:
node .\make-sample.cjs
$env:CODEX_HOME = (Resolve-Path .\usage-records).Path
node .\node_modules\ccusage\src\cli.js codex daily --json --offline --timezone UTC
Expect a daily entry for 2026-11-16 with totalTokens: 1800. UTC makes the grouping match the timestamps in this example.
Three useful jobs
Reconcile input, cache and output
Give Codex the command above and this request, allowing terminal execution in the sample directory:
Use only this project's usage-records. Set CODEX_HOME to its absolute path
for each command. Run ccusage codex daily --json --offline --timezone UTC.
Report totalTokens, inputTokens, cacheReadTokens and outputTokens.
Explain how the cumulative readings are counted.
The fields are 1800, 1350, 150 and 300. The source input counter of 1500 includes cached input; the report separates 150 into cache reads. Adding cache to the raw input again would count it twice.
Summarize monthly activity
node .\node_modules\ccusage\src\cli.js codex monthly --json --offline --timezone UTC
Ask the assistant to list months, tokens and models before suggesting follow-up questions. This sample contains only November 2026, totaling 1800, so it cannot establish a trend. Daily and monthly reports group the same records; do not add their totals together.
Check that a date filter works
node .\node_modules\ccusage\src\cli.js codex daily --since 20261117 --json --offline --timezone UTC
Ask Codex to check for daily: [] and zero totals. A known-empty selection helps distinguish a working filter from a failure to find any logs.
Switch to your own data
After the sample works, open a new PowerShell window in the same installation directory and run the report command to use the default Codex log location. For a custom installation, set CODEX_HOME to its actual directory. Inspect JSON locally and choose the fields to share before handing anything to an assistant. See the official Claude Code source guide for that data source; this recipe does not require a Cursor plugin.
Troubleshooting
No entries appear
Remove date filters first and check that the selected home contains session logs with token_count and model metadata. Older logs may lack the necessary information. Empty output does not establish that no work occurred.
A different terminal reads different records
Environment changes apply to the current process and its future children. A separate, already-open terminal does not pick up a later assignment. Set CODEX_HOME alongside the report command when a fixed source matters.
A day seems missing
Use --timezone UTC to reconcile timestamps before choosing your local timezone. The --since example uses YYYYMMDD; November 17 deliberately excludes this sample's November 16 records.
The dollar estimate differs from a bill
costUSD estimates token value using price data; offline mode uses bundled data. It is neither a subscription invoice nor remaining allowance. Missing logs and pricing revisions matter when interpreting it.
Cost, limits and alternatives
The local MIT-licensed program has no separate usage fee. Offline reports avoid live pricing fetches; your AI client's usage is separate. Reports can only cover available records and cannot reconstruct deleted history. Use the client's account view for allowance questions. For a custom local SQL workflow, consider DuckDB MCP.
FAQ
Does ccusage support Codex?
Yes: select codex daily or codex monthly to focus on that source. An unqualified overview can include other supported agents, so check scope before comparing totals.
Why aren't 1200 and 1800 added together?
They are running totals from the same session. The second event adds 600 to the first 1200, leaving 1800. Summing every cumulative total_token_usage repeats earlier usage.
Should cached tokens be added to input tokens?
Read the field definitions first. This report separates cache reads from inputTokens, while the source input_tokens counter includes cached input. Mixing the two representations produces misleading totals.
Do I need an MCP server?
No. Run the CLI and ask Codex to interpret its JSON. You can also use the reports directly in a terminal without any assistant.
Sources and test scope
Installation, Codex logs, environment variables, source. Checked 2026-11-16.
Windows, Node 24, ccusage 20.0.51 and Codex CLI 0.169.0: Codex executed daily, monthly and filtered reports against synthetic logs, returning 1800, 1800 and 0. No private logs or billing records were inspected. Claude Code data, Cursor and combined-agent reports were not tested.