codex-usage

Token usage tracker for Codex CLI — inspired by ccusage.

Reads directly from Codex CLI's local SQLite database (~/.codex/state_5.sqlite) with zero dependencies.

Install

pip install codex-usage

Or with pipx (recommended):

pipx install codex-usage

Usage

codex-usage [today|week|month|all] [--daily] [--rate-limits] [--json] [--days N]

Examples

# Last 7 days (default)
codex-usage

# Today only
codex-usage today

# This month with daily breakdown
codex-usage month --daily

# All time, JSON output
codex-usage all --json

# Show rate limit window usage
codex-usage --rate-limits

Sample Output

  Last 7 Days
  ──────────────────────────────────────────────
  Sessions   12
  Tokens     3.2M
  Est. Cost  $16.00

  By Model
  ████████████████  3.2M    $16.00  gpt-5.4

  ──────────────────────────────────────────────

  Daily Breakdown
  ──────────────────────────────────────────────
  2026-03-31  ████████████░░  1.1M    $5.50  3 sess
  2026-04-01  ████████░░░░░░  800k    $4.00  2 sess
  2026-04-06  ████████████████  1.3M    $6.50  7 sess
  ──────────────────────────────────────────────

How It Works

Codex CLI stores session metadata in ~/.codex/state_5.sqlite (threads table). Each session records tokens_used as a combined input+output total. Cost estimates use a blended 70% input / 30% output ratio.

Rate limit data is parsed from the most recent rollout JSONL files in ~/.codex/sessions/.

Pricing

Prices are approximate and based on OpenAI's published rates. The tool uses a blended input/output ratio (70/30) since Codex CLI does not separately track input vs output tokens.

Model	Input/1M	Output/1M
gpt-5.4	$5.00	$20.00
o4-mini	$1.10	$4.40
o3	$10.00	$40.00
gpt-4.1	$2.00	$8.00
gpt-4o	$2.50	$10.00

License

MIT