Skip to main content
Trace Codex CLI agent turns and tool calls in Phoenix for full observability.
Trace your Codex CLI sessions in Phoenix with the coding-harness-tracing toolkit — every turn shows up as a trace with the model call, each tool it runs, and token usage, grouped into its session. No application code changes required: the toolkit hooks into Codex’s notify events and streams OpenInference spans to Phoenix.

​
Launch Phoenix

The fastest way to get started with Phoenix is by signing up for a free Phoenix Cloud account. If you prefer, you can also run Phoenix in a notebook, self-host it, or use it directly from your terminal. Go to the settings page in your Phoenix instance to find your endpoint and API key. A self-hosted Phoenix defaults to http://localhost:6006; the API key is only required when auth is enabled.

​
Install

The curl installer is the simplest — it runs a short wizard that saves your Phoenix credentials for you. Use a local clone if you’d rather run the installer from a checkout of the source. macOS / Linux:
Windows (PowerShell):

​
Local clone

The installer prompts for your backend — select Phoenix, then enter your endpoint and optional API key — and your project name. Open a new shell after install so the update takes effect.

​
Configuration

Credentials live in ~/.arize/harness/config.json. To override per category, set environment variables in ~/.codex/arize-env.sh — the notify hook sources this file automatically. Env values take precedence over config.json.
On the Phoenix backend, set the project name with PHOENIX_PROJECT (or PHOENIX_PROJECT_NAME); ARIZE_PROJECT_NAME is Arize-only and ignored here. ARIZE_TRACE_ENABLED is a backend-agnostic harness setting and keeps the ARIZE_ prefix regardless of destination.

​
Redaction controls

Each ARIZE_LOG_* flag accepts "true" or "false" and defaults to "true". Set to "false" to opt out per category:

​
Observe

Once tracing is enabled, Codex activity is streamed to Phoenix. You’ll see:
  • Turn traces — each agent turn (user prompt to assistant response) as a parent LLM span
  • Tool call spans — one per tool decision and result pair
  • Session grouping — all turns from the same session grouped by session.id
  • Model and token usage — model name plus prompt, completion, and total token counts on every turn span
Phoenix session view for a Codex session showing two turns grouped together, each with its own token count, cost, and latency, plus the selected turns' inputs and outputs

Codex turns grouped together in a single session view

Drill into any turn trace to inspect the full span tree, including the parent model generation and child tool calls.
Phoenix trace view showing the trace tree for a Codex turn with an LLM span and nested exec_command and apply_patch tool spans, alongside the span's model, input, token count, cost, and latency

Detailed trace view for a Codex turn

​
Reference

For the full list of environment variables, default file paths, and troubleshooting steps, see the Codex tracing README.

​
Uninstall

​
Resources

Arize Coding Harness Tracing

OpenInference

Codex CLI