---
title: Codex Integration
description: Trace OpenAI Codex CLI sessions -- every turn, tool call, and LLM interaction.
---

# Codex Integration

Trace your Codex CLI sessions. Every turn, tool call, and LLM interaction shows up on your Staso dashboard -- with tokens, latency, and errors.

No code changes. One setup command.

## Setup

```bash
pip install staso
```

**Interactive** -- the wizard guides you through each step:

```bash
staso setup
```

**Or with flags** for scripted/CI setup:

```bash
staso setup --target codex \
  --api-key ak_... \
  --workspace my-workspace \
  --environment default \
  --agent-id my-agent
```

Start a Codex session. Traces flow automatically.

## What Shows Up on the Dashboard

Each conversation turn becomes a trace:

| Span | Kind | What It Captures |
|------|------|-----------------|
| **Turn** (root) | `agent` | Total duration, prompt, model, final response, aggregated token usage |
| **LLM calls** | `llm` | Model, input/output/cached/reasoning tokens, response content |
| **Tool calls** | `tool` | Tool name, input, output, exact execution duration |

All turns from the same Codex session are grouped together.

## Setup Options

| Flag | Default | Description |
|------|---------|-------------|
| `--api-key KEY` | *required* | Staso API key (`ak_...`). Falls back to `STASO_API_KEY` env var |
| `--workspace SLUG` | `default` | Workspace identifier |
| `--environment ENV` | `default` | Environment tag |
| `--agent-id ID` | | Agent ID shown on dashboard |
| `--scope` | `global` | `global` writes to `~/.codex/hooks.json`, `project` writes to `.codex/hooks.json` |
| `--auto-sync` | | Auto-sync hook config on each session start |

## Scope

**Global** (default) traces every Codex session on your machine:

```bash
staso setup --target codex --api-key ak_... --scope global
```

**Project** traces only sessions in the current directory:

```bash
staso setup --target codex --api-key ak_... --scope project
```

## Hook Events

Codex supports 5 hook events:

| Event | What It Does |
|-------|-------------|
| `SessionStart` | Initialize session state, find transcript file, auto-sync if enabled |
| `UserPromptSubmit` | Start a new turn, record prompt and transcript position |
| `PreToolUse` | Record tool start time for duration calculation |
| `PostToolUse` | Send tool span with input, output, and precise duration |
| `Stop` | Parse transcript for LLM data, send LLM + turn spans |

## LLM Span Extraction

Codex hooks parse the session transcript files at `~/.codex/sessions/` to extract LLM usage data. Each turn's LLM call becomes its own span with:

- Model name (e.g. `gpt-5.4`)
- Input tokens, output tokens, total tokens
- Cached input tokens, reasoning output tokens
- Response content

## Status

Check your current configuration:

```bash
staso status --target codex
```

## Upgrading

```bash
staso update
```

This upgrades the staso package and syncs your hook configuration. Or manually:

```bash
pip install -U staso
staso sync
```

To enable automatic syncing on each session start:

```bash
staso sync --enable-auto-sync
```

## Differences from Claude Code

Codex has a simpler hook model:

- **5 hook events** (vs Claude Code's 10) -- no subagent tracking, no failure-specific events
- **No SessionEnd event** -- stale session state is garbage-collected automatically after 24 hours
- **Env vars embedded in command** -- Codex doesn't support an `env` section in its hook config, so credentials are embedded in the hook command string

## Uninstalling

Remove all Staso hooks from Codex and clean up state files:

```bash
staso uninstall --target codex
```

This removes hook entries from `~/.codex/hooks.json`, disables the `codex_hooks` feature flag in `config.toml`, and deletes cached state files.
