@better-ccusage/codex
v1.2.7
Usage analysis tool for OpenAI Codex sessions
0/weekUpdated 1 months agoMITUnpacked: 6.8 KB
Published by cobra91
npm install @better-ccusage/codex
@better-ccusage/codex
> Analyze OpenAI Codex CLI usage logs with the same reporting experience as better-ccusage.
> ⚠️ Beta: The Codex CLI support is experimental. Expect breaking changes until the upstream Codex tooling stabilizes.
Quick Start
``bashRecommended - always include @latest
npx @better-ccusage/codex@latest --help
bunx @better-ccusage/codex@latest --help # ⚠️ MUST include @latest with bunx
Alternative package runners
pnpm dlx @better-ccusage/codex
pnpx @better-ccusage/codex
Using deno (with security flags)
deno run -E -R=$HOME/.codex/ -S=homedir -N='raw.githubusercontent.com:443' npm:@better-ccusage/codex@latest --help
`
> ⚠️ Critical for bunx users: Bun 1.2.x's bunx prioritizes binaries matching the package name suffix when given a scoped package. For
, it looks for a codex binary in PATH first. If you have an existing codex command installed (e.g., GitHub Copilot's codex), that will be executed instead. Always use bunx @better-ccusage/codex@latest with the version tag to force bunx to fetch and run the correct package.$3
Since
npx @better-ccusage/codex@latest is quite long to type repeatedly, we strongly recommend setting up a shell alias:`bash
bash/zsh: alias better-ccusage-codex='bunx @better-ccusage/codex@latest'
fish: alias better-ccusage-codex 'bunx @better-ccusage/codex@latest'
Then simply run:
better-ccusage-codex daily
better-ccusage-codex monthly --json
`> 💡 The CLI looks for Codex session JSONL files under
(defaults to ~/.codex).Common Commands
`bash
Daily usage grouped by date (default command)
npx @better-ccusage/codex@latest dailyDate range filtering
npx @better-ccusage/codex@latest daily --since 20250911 --until 20250917JSON output for scripting
npx @better-ccusage/codex@latest daily --jsonMonthly usage grouped by month
npx @better-ccusage/codex@latest monthlyMonthly JSON report for integrations
npx @better-ccusage/codex@latest monthly --jsonSession-level detailed report
npx @better-ccusage/codex@latest sessions
`Useful environment variables:
-
– override the root directory that contains Codex session folders
- LOG_LEVEL – controla consola log verbosity (0 silent … 5 trace)ℹ️ The CLI now relies on the model metadata recorded in each
turn_context. Sessions emitted during early September 2025 that lack this metadata are skipped to avoid mispricing. Newer builds of the Codex CLI restore the model field, and aliases such as gpt-5-codex automatically resolve to the correct pricing entry.
📦 For legacy JSONL files that never emitted turn_context metadata, the CLI falls back to treating the tokens as gpt-5 so that usage still appears in reports (pricing is therefore approximate for those sessions). In JSON output you will also see "isFallback": true on those model entries.Features
- 📊 Responsive terminal tables shared with the
better-ccusage` CLI- 💵 Offline-first pricing cache with automatic refresh when needed
- 🤖 Per-model token and cost aggregation, including cached token accounting
- 📅 Daily and monthly rollups with identical CLI options
- 📄 JSON output for further processing or scripting
Documentation
For detailed guides and examples, visit better-ccusage.com/guide/codex.
Sponsors
License
MIT © @cobra91