Skip to main content
  1. Sign up — Create an account at platform.respan.ai
  2. Create an API key — Generate one on the API keys page
  3. Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page
Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.
{
  "mcpServers": {
    "respan-docs": {
      "url": "https://docs.respan.ai/mcp"
    }
  }
}

​
What is Codex CLI?

Codex CLI is OpenAI’s open-source coding agent that runs in the terminal. It can reason about your codebase, make file edits, execute shell commands, and handle multi-step coding tasks autonomously.

​
Setup

Prerequisite: Codex CLI must be installed before integrating with Respan.
npm install -g @openai/codex
1

Install the Respan CLI

npm install -g @respan/cli
2

Set your API key

export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
3

Integrate

respan integrate codex-cli
This automatically configures Codex CLI’s notify hook to send traces to Respan.
4

Use Codex CLI normally

codex "Add input validation to the user registration form"
All conversations are now traced automatically — no changes to your workflow.
5

View your traces

Open the Traces page to see your Codex CLI conversations with full hierarchy — reasoning, tool calls, and responses.

​
Configuration

Customize the integration with flags: 
respan integrate codex-cli --customer-id "frank" --project-id "proj-123" --span-name "my-app"
FlagEnv varDefaultDescription
--global—BothWrite user-level global config (~/.codex/config.toml).
--local—BothWrite per-project config (.codex/respan.json).
--customer-idRESPAN_CUSTOMER_ID—Customer/user identifier for traces.
--project-idRESPAN_PROJECT_ID—Respan project ID.
--span-name—codex-cliRoot span name.
--workflow-name—codex-cliWorkflow name for traces.
--attrs——Custom attributes JSON (e.g. '{"env":"prod"}').
--base-urlRESPAN_BASE_URLhttps://api.respan.ai/apiRespan API base URL.
--dry-run——Preview changes without writing files.

​
Captured Data

DataDescription
User promptThe user’s input text
Assistant responseCodex CLI’s final response
Thinking blocksReasoning content
Tool callsTool name, input, and output (file operations, shell commands, etc.)
Token usageInput, output, and cache tokens (when available)
TimingStart time, end time, latency
ModelModel name used (e.g. codex-mini, o4-mini)

​
Span Types

Spanlog_typeDescription
RootagentThe complete conversation turn
ThinkinggenerationReasoning blocks
TooltoolTool invocations (file reads, writes, shell commands, etc.)

​
Uninstall

To remove the integration: 
respan integrate codex-cli --remove