See how much your OpenAI Codex sessions cost - broken down by day, month, or session - right from your terminal.

Inspired by @ccusage/codex, codexusage is a ground-up Rust rewrite built for users who need a significantly faster and lighter alternative to scan large session histories.

cargo install codexusage

# Daily usage summary
codexusage daily

# Monthly report as JSON
codexusage monthly --json

# Last 7 days only
codexusage daily --last-days 7

# Current project only
codexusage daily --current-dir

# Custom session directory
codexusage session --session-dir /path/to/sessions

# Ignore Pi runtime sessions
codexusage daily --no-pi

Filter by date range:

codexusage daily --since 2026-03-01 --until 2026-03-31

Skip network and use cached pricing:

codexusage daily --offline

JSON output for scripts and dashboards:

codexusage daily --json

Limit usage to one project directory and its descendants:

codexusage daily --project-dir /path/to/project
codexusage session --current-dir

Monitor today's usage live in your terminal. The screen refreshes automatically and shows a rolling burn rate so you can see how fast tokens are being consumed:

codexusage watch

Custom refresh interval (default 5 seconds):

codexusage watch --interval 10

Opt in to per-model burn-rate columns inside the watch table:

codexusage watch --per-model-burn-rate

Sample output:

Current Day Codex Usage Watch
Date: 2026-03-11  Window: 60 minutes

+-----------+------------+----------------+
| Metric    | Today      | Burn Rate (/h) |
+-----------+------------+----------------+
| Input     |       450K |            56K |
| Cache     |       120K |            15K |
| Output    |        30K |             4K |
| Reasoning |        12K |             2K |
| Total     |       612K |            77K |
| Cost      |      $0.85 |          $0.11 |
| Updated   | 2026-03-11 |       14:32:23 |
+-----------+------------+----------------+

+------------------------------------+
| Burn Rate History                  |
+------------------------------------+
|         ▆                ─ $0.14/h |
|       ▆███▆              ─ $0.10/h |
|   ▂▅███████▅▃            ─ $0.06/h |
| ▁▄███████████▃▁          ─ $0.02/h |
| 10:30 ───── 14:30                  |
+------------------------------------+

Watch mode does not support --json, --since, --until, or --last-days. It runs in the terminal's alternate screen, ignoring keyboard and scroll input without echoing it; press Ctrl-C to exit and restore the previous screen, cursor, and input mode. Use --per-model-burn-rate to append one burn-rate column per active model, with aggregate Burn Rate (/h) kept as the rightmost column. When the terminal is too narrow to fit every per-model column in one table, watch mode automatically stacks multiple table blocks vertically, repeating the Metric column in each block while keeping Today in the first block and aggregate Burn Rate (/h) in the final block. Watch mode also refreshes Codex 5h and weekly usage-limit bars every 3 minutes from ${CODEX_HOME:-~/.codex}/auth.json when ChatGPT auth is available. Missing auth, expired tokens, --offline, and usage API failures are shown as an unavailable limit status without stopping the watch screen. Reset countdowns are calculated locally between usage refreshes. When enough terminal space is available, watch mode also shows a compact cost burn-rate graph built from trailing 30-minute windows sampled every 15 minutes. The graph uses the past 8 hours on larger terminals and falls back to the past 4 hours on tighter screens.

Commands:

• daily - group usage by day
• monthly - group usage by month
• session - group usage by session
• watch - live current-day monitor with burn rate

Flags:

• --json - emit structured JSON instead of a table
• --since / --until - inclusive date filters
• --last-days N / -L N - show the last N calendar days (daily only)
• --timezone - IANA timezone for grouping
• --offline - use cached pricing, never hit the network
• --refresh-pricing - force a pricing refresh
• --no-cache-cost - treat cache-read input tokens as free in cost calculations
• --exclude-cache-read - subtract cache-read input tokens from reported input/total usage and hide cache-read columns
• --session-dir - override session directory (repeatable)
• --no-pi - do not automatically scan Pi runtime sessions
• --project-dir PATH - only include sessions whose logged working directory is under this project path
• --current-dir - shortcut for --project-dir with the current directory
• --threads N - scanner worker count
• --no-scan-index - disable the persistent scan index for report commands
• --number-format full - show full token counts instead of K/M/B/T
• watch --per-model-burn-rate - show per-model burn-rate columns in the live watch table

--last-days cannot be combined with --since or --until.

By default, codexusage scans CODEX_HOME/sessions (or ~/.codex/sessions when CODEX_HOME is not set). It also discovers Pi sessions under ${PI_CODING_AGENT_SESSION_DIR:-${PI_CODING_AGENT_DIR:-~/.pi/agent}/sessions} and includes assistant usage from the openai-codex provider. Use --no-pi to disable Pi discovery. Supplying any --session-dir keeps its existing override behavior and disables automatic roots. Daily, monthly, and session reports maintain a local scan index under the user cache directory so repeated reports only parse changed session bytes. If the index cannot be read or written, the report still runs and emits a warning. Use --no-scan-index for a one-off full scan.

Daily Codex Usage Report

+------------+--------------+-------+-------+--------+-----------+-------+-------+
| Date       | Model        | Input | Cache | Output | Reasoning | Total |  Cost |
+------------+--------------+-------+-------+--------+-----------+-------+-------+
| 2026-03-01 | TOTAL        |  120K |   30K |     8K |        4K |  158K | $0.20 |
|            |   gpt-5      |  120K |   30K |     8K |        4K |  158K | $0.20 |
+------------+--------------+-------+-------+--------+-----------+-------+-------+
| 2026-03-02 | TOTAL        |   90K |   20K |     6K |        2K |  118K | $0.03 |
|            |   gpt-5-mini |   90K |   20K |     6K |        2K |  118K | $0.03 |
|            | GRAND TOTAL  |  210K |   50K |    14K |        6K |  276K | $0.23 |
+------------+--------------+-------+-------+--------+-----------+-------+-------+

Pricing data is cached locally and refreshed automatically when stale. Use --offline to skip network access entirely, or --refresh-pricing to force an update. Use --no-cache-cost to keep cache-read tokens in token totals while excluding their cached-input price from cost totals. Use --exclude-cache-read to report fresh-input usage only; it also treats cache-read input as free for cost calculations.

Live pricing refreshes use the system CA store through reqwest's Rustls backend. Minimal containers or stripped-down CI images may need a CA bundle such as ca-certificates installed for refreshes to succeed.

codexusage was built because @ccusage/codex became unusably slow on large session directories. The table below shows a side-by-side comparison on the same dataset.

Test environment: 4.4 GB across 7726 session files, Intel i7-1185G7 (8 logical CPUs).

Notes:

• @ccusage/codex was already cached by Bun; the one-time download is not counted.
• Results reflect this specific machine and dataset, not a universal guarantee.

Build from source:

cargo build --release

Source builds require a working C toolchain and cmake because the reqwest TLS stack pulls in aws-lc-rs.

Quality commands:

just fmt
just clippy
just test
just bench