Codex Usage Analyzer

A fast, database-free Rust CLI for analyzing OpenAI Codex CLI usage, token consumption, estimated costs, latency, and context composition from local rollout-*.jsonl session files.

Fast and lightweight: rollout files are processed in parallel, with no database or background service required. The optimized Linux x86-64 binary is about 3.9 MB.

Features

• Track Codex token usage and estimated API costs over custom time ranges
• Group results by model, reasoning effort, directory, or session
• Inspect end-to-end latency, time to first token (TTFT), medians, and p95
• Measure agent-hours and effective parallelism from completed turns
• Analyze context composition and identify token-heavy tools and content
• Export reports as human-readable tables, JSON, or CSV
• Export versioned, structured JSON for telemetry ingestion
• Keep session data local with no database, account, or background service

Cost estimates select the price that was effective on each event's UTC date. Historical price changes are sourced from the OpenAI API changelog, while current Codex rates come from the ChatGPT rate card. When OpenAI publishes only an effective date, the new rate is applied from 00:00 UTC on that date.

Build

cargo build --release

The binary is written to target/release/codex-usage-analyzer.

Usage

# Today's usage
codex-usage-analyzer --today

# Last seven days, broken down by model
codex-usage-analyzer --last 7d --by model

# Last seven days, broken down by model and reasoning effort
codex-usage-analyzer --last 7d --by model,effort

# JSON for all available rollouts
codex-usage-analyzer report --last all --format json

# Versioned JSON envelope for telemetry ingestion
codex-usage-analyzer report --last 1h --by model,effort,directory,session --format telemetry-json

# Latest captured usage snapshot
codex-usage-analyzer status

# Latency statistics for the last seven days, broken down by model
codex-usage-analyzer latency --last 7d --by model

# Agent-hours and effective parallelism over seven days
codex-usage-analyzer workflow --last 7d

# Daily results broken down by model
codex-usage-analyzer workflow --last 7d --group day --by model

# Estimated composition of input and cached-input context over seven days
codex-usage-analyzer breakdown --last 7d

# All available rollouts
codex-usage-analyzer breakdown

The default rollout directory is ~/.codex/sessions. Override it with --rollouts PATH or CODEX_USAGE_ROLLOUTS.

Supported report options include:

• --today, --last, --from, and --to
• --group all|day|week|month (default: all)
• --by model|effort|directory|session, with comma-separated dimensions such as --by model,effort
• --format table|json|csv|telemetry-json
• --timezone IANA_NAME
• --output PATH

telemetry-json is available for report. It emits a versioned envelope with the effective time window, aggregation settings, structured dimensions, and numeric usage and cost metrics. Every dimension explicitly selected with --by, including directory and session, is included unchanged. The output contains no prompt, response, tool-output, or repository-file content.

latency accepts the same range, grouping, timezone, and output options as report, with table, json, and csv formats. It shows sample counts, averages, medians, and p95 values. Latency fields are emitted in milliseconds in JSON and CSV; the table uses human-readable durations. Older rollouts may not contain latency measurements, so missing values are excluded from the sample counts and aggregates.

workflow accepts the same range, --group all|day|week|month, --by model|effort|directory|session, timezone, and --format table|json|csv options as latency. The default grouping is all. Agent-hours sum the recorded durations of completed turns within each period and group. Active wall-hours measure the union of their time intervals, counting overlaps once within each group. Effective parallelism is agent-hours divided by active wall-hours. Intervals crossing a day or range boundary are split or clipped at that boundary. Turns without a recorded duration are excluded. These measures describe recorded agent activity, not verified human time saved.

breakdown reads context items but does not store them. It allocates the exact reported input, cached-input, output, and reasoning-output totals across categories using the recorded context order. Tokenization, encrypted compaction summaries, model-injected tool schemas, and protocol overhead make the category split an estimate. reasoning_output_tokens is shown separately; depending on the rollout schema, it may be a subset of output_tokens rather than an additional token count. Without a range option, every available rollout is analyzed. breakdown accepts the same --last, --today, --from, and --to options as reports. Use --format table|json|csv and --output PATH as with reports. Code-looking output from file-reading/search commands is classified as repository source. The table groups results hierarchically by family, content kind, and source; for example, Tool outputs → Repository source → rg. JSON exposes the same three-part path as a structured category object, while CSV keeps separate family, kind, and source columns. Detected-code counts are metrics on every hierarchy level. They scan every observable text category, including fenced Markdown, diff hunks, compiler excerpts, prompts, assistant messages, and otherwise mixed tool output. Opaque protocol overhead and the unobserved portion of encrypted compaction summaries cannot be classified. Tool-output kinds include repository source, build/test/lint, search/listings, version control, patches/edits, web/external data, UI/media, process control, data/analysis, system/environment, diagnostics, generic shell, and uncategorized output. Sources such as rg, grep, find, ls, sed, and cat remain individually attributable below those kinds. For patch/edit calls, the call wrapper and metadata are accounted separately from the actual patch or replacement-code payload; the tool's confirmation is reported as a third, distinct result category.