Codex Usage Audit

Analyze Codex session logs with accurate token and cost accounting.

Requirements

• Python 3.11+
• uv
• Codex session logs under ${CODEX_HOME:-~/.codex}/sessions

What it reports

• Last N days of usage (default: 2 days, today + yesterday in local timezone)
• Token categories (disjoint, no double counting):
  • input_uncached_tokens
  • input_cached_tokens
  • output_reasoning_tokens
  • output_non_reasoning_tokens
• Cost by category, model, project, and day
• Top costly sessions

Quick start

uv sync
cp pricing/models.template.toml pricing/models.toml

Fill pricing/models.toml with real USD-per-1M-token rates.

Run

uv run codex-usage report

Examples:

uv run codex-usage report --days 1
uv run codex-usage report --days 3
uv run codex-usage report --calendar-month current
uv run codex-usage report --calendar-month last
uv run codex-usage report --tz utc
uv run codex-usage report --top 20 --out-dir reports
uv run codex-usage report --sessions-dir ~/.codex-personal/sessions
uv run codex-usage report --show-turn-analysis

--calendar-month uses full calendar boundaries in the selected timezone and overrides --days.

Development

uv run pytest -q

CSV output includes:

• summary_by_day.csv
• summary_by_model.csv
• summary_by_project.csv
• top_sessions.csv

--show-turn-analysis also adds turn/duration sections in terminal output and writes summary_by_turn_bucket.csv.