Skip to main content
Trace Codex CLI agent turns, tool calls, and API requests in Arize AX for full observability.
Codex is OpenAI’s open-source CLI coding agent. The Arize Agent Kit instruments Codex notify hook events and exports OpenInference spans to Arize AX and/or Phoenix. Each agent turn is captured as an LLM span with tool calls, token usage, and API request details.

​
Launch Arize

To get started, sign up for a free Arize account and get your Space ID and API Key:
  1. Log in at app.arize.com
  2. Click Settings and copy the Space ID
  3. Open the API Keys tab and create or copy an API key

​
Install

curl -fsSL https://raw.githubusercontent.com/Arize-ai/arize-agent-kit/main/install.sh | bash
The installer detects Codex and guides you through configuration.

​
Dedicated installer

git clone https://github.com/Arize-ai/arize-agent-kit.git
cd arize-agent-kit/codex-tracing
bash install.sh
The installer supports interactive and non-interactive modes: 
# Interactive
bash install.sh

# Non-interactive: Phoenix
bash install.sh --target phoenix

# Non-interactive: Arize AX with native OTLP
bash install.sh --target arize --otlp

# Uninstall
bash install.sh uninstall

​
Manual setup

  1. Set the notify hook in ~/.codex/config.toml:
notify = ["bash", "/path/to/arize-agent-kit/codex-tracing/hooks/notify.sh"]
  1. Create ~/.codex/arize-env.sh with your backend configuration (see Configuration below).

​
Configuration

All env vars go in ~/.codex/arize-env.sh. The notify hook sources this file automatically. Phoenix (self-hosted) — requires jq and curl, no Python: 
export PHOENIX_ENDPOINT="http://localhost:6006"
export ARIZE_TRACE_ENABLED="true"
Arize AX (cloud) — also requires Python with opentelemetry-proto and grpcio: 
export ARIZE_API_KEY="<your-api-key>"
export ARIZE_SPACE_ID="<your-space-id>"
export ARIZE_TRACE_ENABLED="true"
# pip install opentelemetry-proto grpcio

​
Observe

Once tracing is enabled, Codex activity is streamed to Arize AX. 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
  • API request spans — one per API or WebSocket request
  • Session grouping — all turns from the same session grouped by session.id
  • Token usage — prompt, completion, and total token counts on every turn span

​
Environment Variables

VariableRequiredDefaultDescription
ARIZE_TRACE_ENABLEDNotrueEnable or disable tracing
ARIZE_API_KEYFor AX-Arize AX API key
ARIZE_SPACE_IDFor AX-Arize AX space ID
ARIZE_OTLP_ENDPOINTNootlp.arize.com:443OTLP gRPC endpoint (on-prem Arize)
PHOENIX_ENDPOINTFor Phoenixhttp://localhost:6006Phoenix collector URL
PHOENIX_API_KEYNo-Phoenix API key (if auth enabled)
ARIZE_PROJECT_NAMENoWorking dir basenameProject name in Arize/Phoenix
ARIZE_USER_IDNo-User identifier added to all spans as user.id
ARIZE_DRY_RUNNofalsePrint spans to log instead of sending
ARIZE_VERBOSENofalseEnable verbose logging
ARIZE_LOG_FILENo/tmp/arize-codex.logLog file path (empty to disable)

​
Troubleshooting

ProblemFix
Spans not appearing in PhoenixVerify Phoenix is running (curl -s http://localhost:6006/healthz), check env vars in ~/.codex/arize-env.sh
Spans not appearing in Arize AXVerify ARIZE_API_KEY and ARIZE_SPACE_ID in ~/.codex/arize-env.sh, ensure Python deps (python3 -c "import opentelemetry; import grpc")
jq required errorInstall jq: brew install jq (macOS) or apt-get install jq (Linux)
Session state issuesRemove stale state: rm -rf ~/.arize-codex/state_*.json
Want verbose loggingSet ARIZE_VERBOSE=true in ~/.codex/arize-env.sh
Want to test without sendingSet ARIZE_DRY_RUN=true and run Codex

​
Resources