Skip to content
Trazum

Codex session usage

Documentation / Agent integrations / Codex

Import a local Codex rollout to estimate its API-equivalent usage. This is not a subscription invoice or proof of the amount a provider charged.

Read an explicit file#

trazum from-codex ./rollout.jsonl --label coding -o usage.jsonl
trazum bill ./rollout.jsonl --table
trazum profile usage.jsonl
trazum plan usage.jsonl -o plan.json
trazum verify plan.json --against newer-usage.jsonl

from-codex accepts a file or directory. Directory reads recurse through .jsonl and .ndjson files; from-codex never looks in your Codex home by itself. Since 2.7.0, trazum bill with no path does: it reads $CODEX_HOME/sessions and $CODEX_HOME/archived_sessions (~/.codex when CODEX_HOME is unset, the folders Codex's own source names), names each folder on stderr before reading it, and splits the statement by agent when Claude Code or Gemini CLI sessions were read too. Decompress archives before importing them. Without -o, normalized JSONL goes to stdout; diagnostics go to stderr. Conversion with no attributable records fails instead of writing an empty output.

bill detects this format in explicitly supplied inputs. The browser Bill also accepts uploaded rollout files and converts them locally. For MCP workflows, call import_usage with format: "codex", rollout text and an optional explicit label. Pass its normalized log to the usage tools and preserve the import diagnostics alongside their reports. CLI conversion remains available; neither route establishes source completeness. The HTTP /usage/import also accepts format: "codex" and transcript text, with an optional explicit label of at most 200 characters. It is available since 2.6.0. Both its request and complete JSON response are capped at 1,000,000 UTF-8 bytes; overflow returns 400. Do not blindly split and recombine snapshots to fit: counter/model context and per-request deduplication affect the result. Preserve diagnostics even when the normalized log is empty; empty does not mean free usage. The HTTP savings endpoints consume the normalized log, with log and plan sharing the verification request cap. Raw conversation text is not required by savings analysis.

What is counted#

The converter reads session_meta, model-bearing turn_context, and event_msg / token_count telemetry. A usage snapshot is retained only when its cumulative delta matches its last-call counts. Identical cumulative snapshots are duplicates, including repeated rate-limit updates. Per-session high-water counters survive rewinds and session switches within a file. A rewind cannot establish a new billable origin: only a corroborated progression beyond the previous high-water mark can contribute new usage.

Cached input is subtracted from ordinary input and retained separately. Reasoning output is already inside output tokens and is not added twice. Models retain their recorded names. Unknown models stay unpriced; no model alias or price is guessed. The timestamp is retained only when valid.

Only model, timestamp, session ID, optional caller-supplied label and token counts survive conversion. Prompts, responses, instructions, working paths and other session metadata are discarded. Output still contains session IDs and labels; review those before sharing it.

What cannot be established#

  • Restored totals and aggregate jumps do not establish individual calls or their historical models. They establish a baseline for later deltas only.
  • Missing model context, invalid counters, counter resets, synthetic context-window fills and nonzero cache-write counters are excluded.
  • A partial file may lack earlier context. Repeated copies of the same rollout supplied as separate files are not deduplicated across files.
  • Codex telemetry can be estimated, replayed or incomplete. Even a fully converted file does not prove complete provider billing or subscription use.

Conversion reports duplicate and excluded counts separately. bill JSON adds importEvidence for Codex inputs: source, basis, files, duplicates, missingModel, unsupported, unparseable and complete. complete means no conversion exclusions were observed, not that billing is complete. Receipt gaps still records unpriced models and other profile gaps. Consumers that retain only the standard receipt fields must retain import evidence separately. Normalized JSONL cannot carry excluded snapshots: preserve conversion stderr alongside that file when auditing or planning savings.

Upstream format evidence#

Implementation was checked against OpenAI Codex commit 97239fd052db455bd08c41afcdab738e0fe83b87: protocol counters and rollout context and Responses usage mapping. The protocol distinguishes token-count telemetry from exact raw response completion usage. Future upstream changes may require an adapter update; unsupported shapes are excluded rather than interpreted as zero-cost calls.