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

# Codex Integration

Trace your Codex CLI sessions. Every turn and tool call shows up on your Staso dashboard -- with duration and errors.

No code changes. One setup command.

## Setup

```bash
pip install staso
```

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

That's it. Start a Codex session and traces flow automatically.

## What Shows Up on the Dashboard

Each conversation turn becomes a trace. Within each trace:

| Span | Kind | What It Captures |
|------|------|-----------------|
| **Turn** (root) | `agent` | Total duration, prompt, model, final response |
| **Tool calls** | `tool` | Tool name, input, output, exact execution duration |

All turns from the same Codex session are grouped together on your dashboard.

## Setup Options

| Flag | Description |
|------|-------------|
| `--api-key KEY` | Staso API key (`ak_...`). Falls back to `STASO_API_KEY` env var. |
| `--workspace SLUG` | Workspace identifier |
| `--environment ENV` | Environment tag (default: `production`) |
| `--agent-id ID` | Agent ID shown on dashboard |
| `--scope {global,project}` | `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 project directory:

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

## Upgrading

After upgrading the staso package, run `staso sync` to update your hook configuration:

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

To enable automatic syncing on each session start, add `--auto-sync` during setup or run:

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

## Differences from Claude Code

Codex has a simpler hook model than Claude Code:

- **5 hook events** (vs Claude Code's 10) -- no subagent tracking, no failure-specific events
- **No LLM span extraction** -- turn spans show total duration but not per-LLM-call token breakdowns
- **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

## Disabling

Remove the Staso hooks from your Codex hooks file (`~/.codex/hooks.json` for global, `.codex/hooks.json` for project). Delete the Staso entries from the `hooks` section.
