better-ccusage.
> ⚠️ Beta: The Codex CLI support is experimental. Expect breaking changes until the upstream Codex tooling stabilizes.
## Quick Start
```bash
# Recommended - 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 `@better-ccusage/codex`, 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.
### Recommended: Shell Alias
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 `CODEX_HOME` (defaults to `~/.codex`).
## Common Commands
```bash
# Daily usage grouped by date (default command)
npx @better-ccusage/codex@latest daily
# Date range filtering
npx @better-ccusage/codex@latest daily --since 20250911 --until 20250917
# JSON output for scripting
npx @better-ccusage/codex@latest daily --json
# Monthly usage grouped by month
npx @better-ccusage/codex@latest monthly
# Monthly JSON report for integrations
npx @better-ccusage/codex@latest monthly --json
# Session-level detailed report
npx @better-ccusage/codex@latest sessions
```
Useful environment variables:
- `CODEX_HOME` – 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](https://better-ccusage.com/guide/codex/)**.
## Sponsors
## License
MIT © [@cobra91](https://github.com/cobra91)