---
title: Codex
description: How ClawMetry observes Codex — where its data lives, the environment variables that move it, what cost data is real, and the traps in its store.
eyebrow: 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 id** | `codex` |
| **Category** | Terminal coding agent |
| **Vendor** | OpenAI |
| **Tier** | Paid tier (Starter and up) |
| **Upstream** | [github.com/openai/codex](https://github.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

| Variable | Effect |
|---|---|
| `CODEX_HOME` | Codex's own home override, honoured directly |

See [Environment variables](/docs/config/environment/) 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.

:::note 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](/docs/ops/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.