Claude Code | Respan Docs

Claude Code is Anthropic’s agentic coding tool that lives in your terminal. Respan gives you hierarchical traces of every conversation including thinking blocks, tool calls, and token usage — and gateway routing through the Anthropic-compatible Respan endpoint.

Set up Respan

Create an account at platform.respan.ai and grab an API key. For gateway, also add credits or a provider key.

Run npx @respan/cli setup to set up with your coding agent.

Example projects

Claude Code hook source

Tracing

Gateway

Claude Code stores conversation transcripts as JSONL files. The Respan hook reads new entries on the Stop event and exports them as structured traces.

Setup

Prerequisites

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

Set environment variables

Add to your shell profile (.bashrc, .zshrc, or PowerShell $PROFILE):

$ export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
$ export TRACE_TO_RESPAN="true"

Download the hook script

$ 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

Configure Claude Code settings

Add the hook to ~/.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 }

View your trace

Open the Traces page to see hierarchical conversation traces with thinking blocks, tool calls, and token usage.

Captured data

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-5-20250929`).

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.).

Debugging

Check the log file for issues.

$ tail -f ~/.claude/state/respan_hook.log

The hook tracks processed turns in ~/.claude/state/respan_state.json. Delete it to reprocess all turns.

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.