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.
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/Respan/respan-example-projects/main/example_scripts/python/claude_code/respan_hook.py
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:
Data Description User prompt The user’s input text Assistant response Claude’s final response Thinking blocks Extended thinking content Tool calls Tool name, input, and output Token usage Input, output, and cache tokens Timing Start time, end time, latency Model Model name (e.g., claude-sonnet-4-20250514)
Span Types Span log_typeDescription Root agentThe complete conversation turn Thinking generationExtended thinking blocks Tool toolTool invocations (Read, Write, Bash, etc.)
Trace Fields Field Value Description 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 usage Input token count completion_tokensFrom usage Output token count cache_creation_prompt_tokensFrom usage Cache 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 Issue Solution No traces appearing Check TRACE_TO_RESPAN=true is set API errors Verify RESPAN_API_KEY is correct Missing thinking Ensure extended thinking is enabled in Claude Code Duplicate traces Clear 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 Feature Cursor Claude Code Hook type Multiple real-time hooks Single Stop hook Data source JSON via stdin JSONL transcript files Timing Real-time Post-hoc (after response) Token usage Not available Full usage details Cache info Not available Cache creation/read tokens
Source Code The full source code is available on GitHub: Respan/respan-example-projects/claude_code
References 
