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

pip install staso

Interactive -- the wizard guides you through each step:

staso setup

Or with flags for scripted/CI setup:

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.

Staso parses every Codex tool into a human-readable card on your dashboard. Patches show unified diffs with +/- highlighting. Shell output shows exit codes and PTY session info. Plans render as step lists with status badges.

Category	Tools	What You See
Shell & execution	exec_command, write_stdin, shell, shell_command	Command with `$` prompt, stdout/stderr split, exit code + wall time + PTY session badges
File operations	apply_patch, list_dir	Unified diff with file headers and +/- lines, directory listings
Code execution	js_repl, js_repl_reset	Syntax-highlighted JavaScript, execution results
Planning	update_plan, request_user_input	Step list with pending/in-progress/completed badges, multi-choice questions with option pills
Multi-agent	spawn_agent, send_message, send_input, followup_task, wait_agent, close_agent, list_agents	Agent spawn with task names, message routing, wait status per agent, agent lifecycle
Batch jobs	spawn_agents_on_csv, report_agent_job_result	CSV path with concurrency settings, job results
System	view_image, tool_search, tool_suggest, request_permissions, MCP resource tools	Image cards, search results, permission requests with file system/network scopes

32 tool types total. Both hook-fired tools (shell, exec_command) and transcript-only tools (apply_patch, spawn_agent) are captured.

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:

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

Project traces only sessions in the current directory:

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:

staso status --target codex

Upgrading

staso update

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

pip install -U staso
staso sync

To enable automatic syncing on each session start:

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:

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.