CClawMetryDocs

Runtime reference

Codex#

Codex writes date-partitioned rollout transcripts. The filename carries both the start timestamp and the session UUID, and the wire format is a tagged union that records the model per turn — so a session that switched models is priced per turn.

Runtime idcodex
CategoryTerminal coding agent
VendorOpenAI
TierPaid tier (Starter and up)
Upstreamgithub.com/openai/codex

Where the data comes from#

ClawMetry reads these locations, in order, and never writes to any of them.

  • $CODEX_HOME/sessions/YYYY/MM/DD/rollout-<ISO-ts>-<uuid>.jsonl (default ~/.codex/sessions/)

Format. One JSON object per line wrapping a RolloutItem: session_meta, turn_context, response_item, event_msg, compacted.

Environment variables#

VariableEffect
CODEX_HOMECodex's own home override, honoured directly

See Environment variables for the variables that apply to every runtime.

Tokens and cost#

Tokens. Real, on disk, but only once the model has responded: the token_count event carries a running cumulative total and ClawMetry takes the last one seen.

Cost. Not written by Codex. Derived from the token split and the turn_context.model value.

Why this section exists

Runtimes differ enormously in what they persist. Rather than showing a plausible number everywhere, ClawMetry reports what the store actually contains and marks the rest unknown. A cost of $0.00 and a cost of unknown mean different things, and the dashboard keeps them different.

Things worth knowing#

  • A session cut off before any model response has no token_count line at all. ClawMetry reports zero tokens for it rather than estimating.
  • turn_context.model — not the session header — is the authoritative model for a turn.
  • Codex edits files through apply_patch and through shell heredocs. Guard's shell-mutation rule is what keeps no_progress meaningful for shell-first sessions.

Verify it is being read#

bash
# Is this runtime detected, and would this install unlock it?
clawmetry runtimes --json | jq '.runtimes[] | select(.id=="codex")'

# Why is it locked, if it is?
clawmetry runtimes --why codex

# Any sessions ingested yet?
curl -s 'http://localhost:8900/api/local/sessions?limit=5' \
  | jq '.rows[] | {session_id, agent_id, events, cost_usd}'

If detection succeeds but no sessions appear, work through Troubleshooting — the usual causes are a relocated data directory (set the override above), a session limit that is hiding older runs, or a runtime that simply has not written anything yet.

Edit this page View as Markdown Report an issue
Cookie preferences