Trace CLI coding agents

Set up Respan

Sign up — Create an account at platform.respan.ai
Create an API key — Generate one on the API keys page

Overview

CLI coding agents like Claude Code, Codex CLI, Gemini CLI, and OpenCode run in sandboxed terminal environments — making multiple LLM calls, reading files, executing shell commands, and editing code autonomously. Without observability, you have no visibility into what the agent did, how many tokens it consumed, or whether it made the right decisions. This cookbook shows how to add full tracing in 6 steps — no code changes required.

1. Install the CLI

npm install -g @respan/cli

2. Authenticate

respan auth login --api-key YOUR_API_KEY

Replace YOUR_API_KEY with the key from the API keys page. Verify you’re authenticated:

respan whoami

3. Integrate your agent

Run the integration command for your CLI agent:

Claude Code
Codex CLI
Gemini CLI
OpenCode

respan integrate claude-code

This installs a Node.js hook at ~/.respan/hooks/claude-code.cjs and registers it in ~/.claude/settings.json. Every time Claude Code responds, the hook captures the turn and sends it to Respan.

respan integrate codex-cli

This installs a Node.js hook at ~/.respan/hooks/codex-cli.cjs and registers it in ~/.codex/config.toml. After each agent turn, the hook captures session data and sends it to Respan.

respan integrate gemini-cli

This installs a Node.js hook at ~/.respan/hooks/gemini-cli.cjs and registers hooks for AfterModel, BeforeTool, and AfterTool events in ~/.gemini/settings.json. The hook accumulates streaming chunks and sends the complete turn to Respan.

respan integrate opencode

This installs the opencode-otel plugin and writes an OTEL config to .opencode/plugins/otel.json that exports traces to Respan.

4. Add attributes (optional)

Tag traces with customer IDs, project names, or custom metadata for filtering and cost tracking.

Via integrate flags

Claude Code
Codex CLI
Gemini CLI
OpenCode

respan integrate claude-code \
  --customer-id "dev-alice" \
  --workflow-name "feature-work" \
  --project-id "proj_123" \
  --attrs '{"team": "backend", "sprint": "2025-Q3"}'

respan integrate codex-cli \
  --customer-id "dev-alice" \
  --workflow-name "feature-work" \
  --attrs '{"team": "backend"}'

respan integrate gemini-cli \
  --customer-id "dev-alice" \
  --attrs '{"team": "backend"}'

respan integrate opencode \
  --project-id "proj_123" \
  --attrs '{"team": "backend"}'

Via environment variables (per session)

Override attributes for a single session without re-running integrate:

export RESPAN_CUSTOMER_ID="dev-alice"
export RESPAN_METADATA='{"task_id": "JIRA-456", "branch": "feat/dark-mode"}'

For OpenCode, use the standard OTEL variable:

export OTEL_RESOURCE_ATTRIBUTES="team=backend,task_id=JIRA-456"

5. Use your agent as normal

No code changes required. Just run your CLI agent:

Claude Code
Codex CLI
Gemini CLI
OpenCode

claude

Or non-interactively:

claude -p "Refactor the auth module to use JWT tokens"

codex

Or non-interactively:

codex exec "Add unit tests for the user service"

gemini

Or non-interactively:

gemini -p "Explain the database schema in this project"

opencode

Or non-interactively:

opencode run "Fix the failing CI test"

6. View traces

Open Traces to see your agent activity. Each agent turn produces a trace like this:

claude-code (root)
  +-- claude.chat (LLM generation - model, tokens, input/output)
  +-- Thinking (extended reasoning, if present)
  +-- Tool: Bash (shell command)
  +-- Tool: Read (file read)
  +-- Tool: Write (file edit)

Each span includes:

Input/output — The user message and agent response
Model — Which model was used (e.g., claude-opus-4-6, gpt-5.4, gemini-3-flash)
Token usage — Prompt tokens, completion tokens, and reasoning tokens
Cost — Computed automatically from token counts
Latency — Time for each step
Tool details — File paths, shell commands, code edits

Filter traces by customer_identifier, workflow_name, or any custom metadata field to find specific sessions. Go to Users to see per-developer breakdowns of token usage, cost, and session count.

Configuration reference

Integrate flags

Flag	Description
`--customer-id`	Customer identifier for traces (e.g., developer name)
`--workflow-name`	Workflow name for grouping traces
`--span-name`	Root span name (defaults to agent name)
`--project-id`	Respan project ID
`--attrs`	Custom attributes JSON (e.g., `'{"team":"backend"}'`)
`--global`	Apply to all projects (not just current directory)
`--local`	Apply to current project only
`--dry-run`	Preview changes without writing files

Environment variables

Variable	Agents	Description
`RESPAN_API_KEY`	All	Override the stored API key
`RESPAN_CUSTOMER_ID`	Claude Code, Codex, Gemini	Override customer identifier per session
`RESPAN_METADATA`	Claude Code, Codex, Gemini	JSON string merged into span metadata
`RESPAN_WORKFLOW_NAME`	Claude Code, Codex, Gemini	Override workflow name per session
`RESPAN_BASE_URL`	All	Override API endpoint (for enterprise)
`TRACE_TO_RESPAN`	Claude Code	Set to `false` to disable tracing
`CC_RESPAN_DEBUG`	Claude Code	Enable debug logging
`CODEX_RESPAN_DEBUG`	Codex CLI	Enable debug logging
`GEMINI_RESPAN_DEBUG`	Gemini CLI	Enable debug logging

Debug logs

Agent	Log file
Claude Code	`~/.claude/state/respan_hook.log`
Codex CLI	`~/.codex/state/respan_hook.log`
Gemini CLI	`~/.gemini/state/respan_hook.log`

Disabling tracing

Claude Code
Codex CLI
Gemini CLI
OpenCode

Set TRACE_TO_RESPAN to false in .claude/settings.local.json:

{
  "env": {
    "TRACE_TO_RESPAN": "false"
  }
}

Comment out the notify line in ~/.codex/config.toml:

# notify = ["node", "~/.respan/hooks/codex-cli.cjs"]

Remove the hooks from .gemini/settings.json.

Delete .opencode/plugins/otel.json.

Next steps

Monitor an AI agent

Set up evaluation and alerting for agent quality

Track cost per feature

Attribute LLM costs to teams and features

Get started

Features

Admin

Security

Resources

Help & Community

Trace CLI coding agents

Overview

1. Install the CLI

2. Authenticate

3. Integrate your agent

4. Add attributes (optional)

Via integrate flags

Via environment variables (per session)

5. Use your agent as normal

6. View traces

Configuration reference

Integrate flags

Environment variables

Debug logs

Disabling tracing

Next steps

Monitor an AI agent

Track cost per feature

Get started

Features

Admin

Security

Resources

Help & Community

​Overview

​1. Install the CLI

​2. Authenticate

​3. Integrate your agent

​4. Add attributes (optional)

​Via integrate flags

​Via environment variables (per session)

​5. Use your agent as normal

​6. View traces

​Configuration reference

​Integrate flags

​Environment variables

​Debug logs

​Disabling tracing

​Next steps

Monitor an AI agent

Track cost per feature

Overview

1. Install the CLI

2. Authenticate

3. Integrate your agent

4. Add attributes (optional)

Via integrate flags

Via environment variables (per session)

5. Use your agent as normal

6. View traces

Configuration reference

Integrate flags

Environment variables

Debug logs

Disabling tracing

Next steps