@ccusage/codex

> Analyze OpenAI Codex CLI usage logs with the same reporting experience as ccusage.

> ⚠️ Beta: The Codex CLI support is experimental. Expect breaking changes until the upstream Codex tooling stabilizes.

Quick Start

``bash


Recommended - always include @latest

> ⚠️ Critical for bunx users: Bun 1.2.x's bunx prioritizes binaries matching the package name suffix when given a scoped package. For @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 @ccusage/codex@latest with the version tag to force bunx to fetch and run the correct package.

$3

Since npx @ccusage/codex@latest is quite long to type repeatedly, we strongly recommend setting up a shell alias:

`bash


bash/zsh: alias ccusage-codex='bunx @ccusage/codex@latest'

> 💡 The CLI looks for Codex session JSONL files under CODEX_HOME (defaults to ~/.codex).

Common Commands

`bash


Daily usage grouped by date (default command)

- 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 LiteLLM 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 ccusage` CLI
- 💵 Offline-first pricing cache with automatic LiteLLM 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 ccusage.com/guide/codex.

Sponsors

$3

Check out ccusage: The Claude Code cost scorecard that went viral

License

MIT © @ryoppippi