Third-party toolUpdated 2026.11.20

ccusage on Windows: Codex Daily Reports, Monthly Totals and Token Counts

Install ccusage on Windows and run Codex daily and monthly reports. Reconcile cumulative tokens and cache fields with a reproducible sample, plus date-filter fixes.

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.

Subscribe to AI tool picks and practical advice

Get worthwhile tool picks, test findings and important updates in your inbox.

Get a monthly-updated list of AI tools and Skills right away. We email when there are worthwhile tool picks, test findings or important updates. Unsubscribe anytime. Privacy

Almost done: check your inboxClick the button in the confirmation email and you will get the download link for the tool list. If you do not see it, check your spam or Promotions folder.

Past issues

Or follow us on: