Claude Code | Respan Docs

Set up Respan

Sign up — Create an account at platform.respan.ai
Create an API key — Generate one on the API keys page
Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page

Use AI

Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.

1 {
2   "mcpServers": {
3     "respan-docs": {
4       "url": "https://mcp.respan.ai/mcp/docs"
5     }
6   }
7 }

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

Claude Code installed (npm install -g @anthropic-ai/claude-code)
Respan API key
Python 3.8+ with requests library

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:

1 {
2   "hooks": {
3     "Stop": [
4       {
5         "hooks": [
6           {
7             "type": "command",
8             "command": "python ~/.claude/hooks/respan_hook.py"
9           }
10         ]
11       }
12     ]
13   }
14 }

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:

1 {
2   "hooks": {
3     "Stop": [
4       {
5         "hooks": [
6           {
7             "type": "command",
8             "command": "python ~/.claude/hooks/respan_hook.py"
9           }
10         ]
11       }
12     ]
13   }
14 }

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_type`	Description
Root	`agent`	The complete conversation turn
Thinking	`generation`	Extended thinking blocks
Tool	`tool`	Tool invocations (Read, Write, Bash, etc.)

Trace Fields

Field	Value	Description
`trace_unique_id`	`{session_id}_turn_{N}`	Unique per turn
`span_workflow_name`	`claudecode_{session_id}`	Groups all turns in session
`thread_identifier`	`claudecode_{session_id}`	Links turns in Threads view
`prompt_tokens`	From usage	Input token count
`completion_tokens`	From usage	Output token count
`cache_creation_prompt_tokens`	From 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:

1 {
2   "session-abc123": {
3     "last_line": 42,
4     "turn_count": 5,
5     "updated": "2026-01-11T22:49:26Z"
6   }
7 }

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