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://respan.ai/docs/mcp"
    }
  }
}
Claude Code agent tracing visualization
Claude Code is Anthropic’s agentic coding tool that lives in your terminal. With Respan integration, you get hierarchical traces of every conversation including thinking blocks, tool calls, and token usage.

​
How It Works

Claude Code stores conversation transcripts as JSONL files. Our integration uses the Stop hook to parse these transcripts and send structured traces to Respan.
For details on trace structure and span types, see the Observability Data Model.

​
Prerequisites

​
Installation

​
1. Set Environment Variables

Add these to your shell profile (.bashrc, .zshrc, or PowerShell $PROFILE): 
export RESPAN_API_KEY="your-api-key"
export TRACE_TO_RESPAN="true"

# Optional: Enterprise endpoint (default: api.respan.ai)
# export RESPAN_BASE_URL="https://endpoint.respan.ai/api"

# Optional: Enable debug logging
# export CC_RESPAN_DEBUG="true"

​
2. Download the Hook Script

Download the hook script to your Claude Code hooks directory: 
mkdir -p ~/.claude/hooks
curl -o ~/.claude/hooks/respan_hook.py \
  https://raw.githubusercontent.com/respanai/respan-example-projects/main/python/dev-tools/claude-code/respan_hook.py

​
3. Configure Claude Code Settings

Add the hook to your Claude Code settings at ~/.claude/settings.json: 
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python ~/.claude/hooks/respan_hook.py"
          }
        ]
      }
    ]
  }
}
If settings.json already exists, merge the hooks section with your existing configuration.

​
4. Enable Per-Project (Optional)

To enable tracing for specific projects, create .claude/settings.local.json in your project directory: 
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python ~/.claude/hooks/respan_hook.py"
          }
        ]
      }
    ]
  }
}

​
Captured Data

The integration captures rich metadata from Claude Code transcripts:
DataDescription
User promptThe user’s input text
Assistant responseClaude’s final response
Thinking blocksExtended thinking content
Tool callsTool name, input, and output
Token usageInput, output, and cache tokens
TimingStart time, end time, latency
ModelModel name (e.g., claude-sonnet-4-20250514)

​
Span Types

Spanlog_typeDescription
RootagentThe complete conversation turn
ThinkinggenerationExtended thinking blocks
TooltoolTool invocations (Read, Write, Bash, etc.)

​
Trace Fields

FieldValueDescription
trace_unique_id{session_id}_turn_{N}Unique per turn
span_workflow_nameclaudecode_{session_id}Groups all turns in session
thread_identifierclaudecode_{session_id}Links turns in Threads view
prompt_tokensFrom usageInput token count
completion_tokensFrom usageOutput token count
cache_creation_prompt_tokensFrom usageCache creation tokens

​
Debugging

Check the log file for issues: 
tail -f ~/.claude/state/respan_hook.log

​
State File

The hook tracks processed turns in ~/.claude/state/respan_state.json: 
{
  "session-abc123": {
    "last_line": 42,
    "turn_count": 5,
    "updated": "2026-01-11T22:49:26Z"
  }
}
Delete this file to reprocess all turns.

​
Common Issues

IssueSolution
No traces appearingCheck TRACE_TO_RESPAN=true is set
API errorsVerify RESPAN_API_KEY is correct
Missing thinkingEnsure extended thinking is enabled in Claude Code
Duplicate tracesClear state file to reset

​
Example Output

After setup, you’ll see traces in Respan with full hierarchy: 
claudecode_abc123_turn_1 (2.5s)
├── Thinking 1 (0.8s) - "Let me read the file first..."
├── Tool: Read (0.1s) - {"path": "main.py"}
├── Thinking 2 (0.5s) - "I see the issue..."
├── Tool: Write (0.1s) - {"path": "main.py", "content": "..."}
└── Token usage: 1,234 prompt / 567 completion

​
Comparison with Cursor Integration

FeatureCursorClaude Code
Hook typeMultiple real-time hooksSingle Stop hook
Data sourceJSON via stdinJSONL transcript files
TimingReal-timePost-hoc (after response)
Token usageNot availableFull usage details
Cache infoNot availableCache creation/read tokens

​
Source Code

The full source code is available on GitHub: Respan/respan-example-projects/claude_code

​
References