cdxusage

The fastest measured, optimized local Codex usage meter for tokens, sessions, and estimated OpenAI cost.

npx -y github:Krablante/cdxusage monthly

cdxusage is the performance-first Codex usage CLI: the fastest measured and most optimized local meter on the large-history benchmark tracked in this repo. It reads local Codex CLI history and shows daily, monthly, or per-session usage: input tokens, cached input, output, reasoning tokens, and an estimated API-equivalent OpenAI cost.

It is built for large Codex histories. The original npx -y @ccusage/codex@latest path can become painful on big archives: long CPU-bound scans and RAM that scales with the full archive shape. On very large histories, that is the multi-GB failure mode cdxusage avoids by streaming JSONL files, indexing compact per-file summaries, and reusing a small local cache.

On Linux hosts with GNU-compatible perl and xargs -r, cold full scans also use a native batch prefilter. Unsupported hosts and native helper failures fall back to the Node scanner automatically.

No SQLite. No daemon. No provider catalogs. No background service.

Quick Start

Run directly from GitHub:

npx -y github:Krablante/cdxusage monthly

Or from a clone:

git clone https://github.com/Krablante/cdxusage.git
cd cdxusage
node ./bin/cdxusage.mjs monthly

Useful one-off reports:

npx -y github:Krablante/cdxusage daily
npx -y github:Krablante/cdxusage monthly
npx -y github:Krablante/cdxusage session
npx -y github:Krablante/cdxusage monthly --json --include-stats
npx -y github:Krablante/cdxusage session --since 2026-05-01 --sort cost --order desc

Inside a clone, use the local entry point:

node ./bin/cdxusage.mjs daily
node ./bin/cdxusage.mjs monthly --json --include-stats

Later examples use cdxusage as shorthand for your chosen entry point: global install, npx -y github:Krablante/cdxusage, or node ./bin/cdxusage.mjs inside a clone.

What You Get

• daily, monthly, session, and sessions alias
• pretty terminal tables and JSON output
• date filters, timezone, locale, sorting, compact tables
• automatic Codex home discovery on Linux, macOS, Windows, and WSL
• Linux/GNU native batch prefilter with Node fallback
• OpenAI/Codex pricing only, with missing non-OpenAI model prices reported
• offline pricing fallback and disposable local caches
• portable folder build with Linux/macOS shell, Windows CMD, and PowerShell launchers

Auto Discovery

By default, cdxusage does a bounded search only. It checks explicit inputs first, then likely Codex locations:

• --codex-home, --sessions-dir, and CODEX_HOME
• current and near-parent .codex
• ~/.codex
• USERPROFILE\.codex
• APPDATA\Codex
• LOCALAPPDATA\Codex
• WSL mappings for Windows-style paths

It does not crawl your whole disk. Override discovery when needed:

cdxusage monthly --codex-home ~/.codex
cdxusage monthly --sessions-dir ~/.codex/sessions

Pricing

Default pricing mode is auto.

cdxusage reads the resolved Codex home's config.toml. If it sees service_tier = "priority" or legacy service_tier = "fast", it applies OpenAI priority prices to OpenAI models that currently expose official priority rates.

Force standard pricing:

cdxusage monthly --no-priority
cdxusage monthly --speed standard

Force priority pricing:

cdxusage monthly --speed fast
cdxusage monthly --speed fast --priority-models all
cdxusage monthly --speed fast --priority-models gpt-5.5,gpt-5.4-mini

Pricing sources are intentionally OpenAI-only:

1. live OpenAI API pricing docs
2. live OpenAI Priority Processing pricing
3. bundled OpenAI/Codex fallback snapshot

Known official long-context rules are applied when needed. For example, standard GPT-5.5 and GPT-5.4 sessions above 272K input tokens use OpenAI's long-context rates, while priority pricing falls back to standard pricing for long-context requests that OpenAI excludes from Priority Processing.

Non-OpenAI model routes are not guessed. They are reported in pricing.missingModels when stats are enabled.

costUSD is an estimate based on logged input, cached input, and output tokens. It is not an invoice and may differ from subscription or credit accounting screens.

Performance

This project is positioned around the fast path: streaming JSONL, compact per-file cache summaries, and a Linux/GNU native batch prefilter when the host supports it. On the current large-history benchmark, the optimized public build cuts cold full-scan wall time by 62.4%, CPU time by 62.9%, and RAM by 48.5% versus the pre-native public baseline, while static synthetic fixtures still match across small, medium, large, huge, and adversarial cases.

Run the local benchmark helper against your own Codex archive:

npm run benchmark -- --since 2026-05-01 --upstream-timeout 25 --cdxusage-timeout 90

The helper resolves @ccusage/codex@latest and times the actual ccusage-codex binary so RAM reflects the scanner, not the npx wrapper.

Recent local sanity check on a large Codex history, comparing this rollout with the previous public commit 1c084b4:

Tool	Scenario	Time	RAM	Result
cdxusage pre-native baseline	cold app cache	27.80s	0.350 GB	complete
cdxusage native auto scanner	cold app cache	10.46s	0.180 GB	complete
cdxusage pre-native baseline	warm app cache	0.40s	0.166 GB	complete
cdxusage native auto scanner	warm app cache	0.30s	0.143 GB	complete

See docs/benchmark-2026-05-16.md for the same-run command output behind this table.

Cold scans read every matching JSONL file for correctness, including resumed long-lived sessions whose recent events may live in older session files. After the cache is built, the same report is dramatically faster.

The native prefilter reduces the candidate-line byte volume delivered into Node processing; it does not claim lower physical disk reads. bytesRead in --include-stats remains the logical source byte count.

Portable Folder

Build a self-contained folder:

npm run portable:build
cd portable
sh ./cdxusage monthly

Windows:

cd portable
.\cdxusage.cmd monthly

PowerShell:

cd portable
.\cdxusage.ps1 monthly

Portable mode still needs Node.js >=20.19.4, but it does not need npm install.

Compatibility

cdxusage keeps the useful @ccusage/codex UX shape: report modes, JSON, pretty tables, filters, offline mode, and terminal-friendly output. See docs/compatibility.md for details.

Intentional differences:

• binary is cdxusage
• default pricing is auto, not always standard
• impossible calendar dates are rejected
• mixed last_token_usage and cumulative-only total_token_usage is de-duplicated instead of reproducing upstream overcounts
• non-OpenAI model prices are reported missing instead of filled from provider catalogs

Development

npm run check
npm run lint
npm run typecheck
npm test
npm run test:node
npm run test:native
npm run smoke
npm run portable:smoke
npm pack --dry-run --json

Caches live under ${XDG_CACHE_HOME:-$HOME/.cache}/cdxusage/ by default and are safe to delete. Token cache files above --max-cache-bytes (CDXUSAGE_MAX_CACHE_BYTES, default 64 MiB, minimum 1 MiB) are ignored on load and skipped on save.