> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Claude Code (tracing)

> Trace Claude Code conversations with Respan — hook-based tracing, gateway routing, and full observability.

[Claude Code](https://docs.anthropic.com/en/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](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

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

#### Use Respan Gateway

See [Claude Code gateway setup](/docs/gateway/claude-code) to route this integration through the Respan gateway.

#### Example projects

* [Claude Code hook source](https://github.com/respanai/respan-example-projects/tree/main/python/dev-tools/claude-code)

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](https://docs.anthropic.com/en/docs/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`):

**`Bash/Zsh`**

```bash Bash/Zsh
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
export TRACE_TO_RESPAN="true"
```

**`PowerShell`**

```powershell PowerShell
$env:RESPAN_API_KEY = "YOUR_RESPAN_API_KEY"
$env:TRACE_TO_RESPAN = "true"
```

#### Download the hook script

**`Bash/Zsh`**

```bash Bash/Zsh
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
```

**`PowerShell`**

```powershell PowerShell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\hooks"
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/respanai/respan-example-projects/main/python/dev-tools/claude-code/respan_hook.py" -OutFile "$env:USERPROFILE\.claude\hooks\respan_hook.py"
```

#### Configure Claude Code settings

Add the hook to `~/.claude/settings.json`:

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python ~/.claude/hooks/respan_hook.py"
          }
        ]
      }
    ]
  }
}
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) 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.

```bash
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.                          |