Claude Code (tracing)

Claude Code is Anthropic’s agentic coding tool. The Respan session-traces plugin sends each Claude Code turn to Respan as a trace, with a span for every model request and tool call, sub-agents nested under the call that started them, and token, cache and timing data on every request.

Set up Respan

Create an account at platform.respan.ai and grab an API key .

The plugin runs inside Claude Code, so there is no hook script, environment variable or background process to set up. It records as Claude Code works and sends each turn when it finishes, without ever making Claude Code wait.

Paste this into your coding agent:


Help me set up Respan tracing with the Claude Code integration.
Follow https://www.respan.ai/docs/integrations/claude-code.md

If you traced Claude Code with Respan before, through the respan_hook.py script or respan integrate claude-code, remove the old hook as part of this setup. The plugin stops the old hook from sending while it runs, but the old hook stays installed and keeps local copies of your conversations in ~/.claude/state/.

Setup

Prerequisites

Claude Code v2.1.287 or later, or the Claude desktop app with Claude Code v2.1.286 or later. Check with claude --version.
A Respan API key.

Install the plugin

Terminal


claude plugin marketplace add respanai/claude-plugins
claude plugin install session-traces@respan

This traces every Claude Code session on your machine. To trace one project only, add --scope project (shared with the repository) or --scope local (just you) to the install command, from that project’s folder.

Add your API key

In Claude Code, run:


/plugin configure session-traces@respan

Enter your Respan API key. It’s stored in your OS keychain, not in a settings file. If your key belongs to Respan Enterprise, set Respan deployment to enterprise.

Tracing starts with your next Claude Code session.

View your trace

Open the Traces page in the project your API key belongs to. Each turn is a trace named claude-code.

Remove the old hook

Earlier setups ran a hook script on Claude Code’s Stop event, and the script setup also ran it on SubagentStop and PostToolUse. Remove every part of it.

Remove the hook from Claude Code settings

Open ~/.claude/settings.json and delete each entry under hooks whose command runs respan_hook.py or .respan/hooks/claude-code.cjs. Check the Stop, SubagentStop and PostToolUse lists, and delete a list if it’s left empty.

To confirm nothing is left:

Terminal


grep -n -E "respan_hook|\.respan/hooks" ~/.claude/settings.json

Delete the hook script and its local files

The state folder holds the hook’s logs, state and, for the CLI setup, debug copies of your conversations.

Terminal


rm -f ~/.claude/hooks/respan_hook.py ~/.respan/hooks/claude-code.cjs
rm -f ~/.claude/state/respan_*

Remove the environment variables

Delete these from your shell profile (.bashrc, .zshrc, or PowerShell $PROFILE) if you added them: TRACE_TO_RESPAN, RESPAN_CUSTOMER_ID, RESPAN_METADATA, RESPAN_HOOK_DEBUG, and any CC_RESPAN_* variable. Keep RESPAN_API_KEY and RESPAN_BASE_URL if other Respan tools, such as an SDK or the Respan CLI, use them. The plugin doesn’t read any of them.

If you set up tracing with respan integrate claude-code, also delete the TRACE_TO_RESPAN line from the env block of each project’s .claude/settings.local.json. You can keep the project’s .claude/respan.json: the plugin still reads it (see Options).

Captured data

Data	Description
User prompt	The turn’s prompt, on the trace’s root span.
Model requests	One `claude.chat` span per request: what’s new in its input since the previous request (your prompt, tool results and context Claude Code adds), and the response text and tool calls.
System prompt	On the first request of each turn.
Thinking	A `Thinking` span with the streamed thinking text, when there is any.
Tool calls	Tool name, arguments and result. A failed or refused call is marked as an error.
Token usage	Input, output, cache-read and cache-write tokens for each request. Input tokens include the cached part.
Timing	Start and end of every span, and the time to the first streamed chunk of each request (`gen_ai.response.time_to_first_chunk`).
Model	The model that answered each request.

Each text field is limited to 61,440 characters, and a longer value ends with a note of how much was cut.

Sub-agents and long sessions


Session (thread claudecode_<session id>)
├─ Turn 1: claude-code                       root (workflow)
│  ├─ claude.chat                            one span per model request
│  ├─ Tool: Read / Bash / Edit ...
│  └─ Tool: Agent                            the call that started a sub-agent
│     └─ Agent: general-purpose              the sub-agent's run (agent)
│        ├─ claude.chat ...                  its model requests and tokens
│        └─ Tool: Read ...
├─ Turn 2: claude-code                       same session and thread id
└─ ...

One trace per turn. Every turn in a session carries the same session and thread identifier, claudecode_<session id>, so the Threads view and a session_identifier filter show the whole session. Each turn’s root carries a claude_code_turn number in its metadata.
Sub-agents are nested under the Tool: Agent span that started them, with their own model requests, tool calls and tokens. A background sub-agent that finishes after its turn stays in that turn’s trace. Each Agent span carries the sub-agent’s agent_id in its metadata.
During long turns, finished spans are sent every 10 seconds, and the turn’s root span is sent when the turn ends.
A turn that Claude Code starts on its own, such as the one after a background sub-agent reports back, is its own trace.

Span types

Span	`log_type`	Description
`claude-code`	`workflow`	One turn: the prompt in, the final answer out.
`claude.chat`	`chat`	One model request: model, tokens, cost, input and output.
`Tool: <name>`	`tool`	A tool call, such as Read, Bash or Agent.
`Agent: <type>`	`agent`	A sub-agent’s run, under the Agent call that started it.
`Thinking`	`task`	The thinking streamed during a model request.

Options

Option	Default	Description
Respan API Key	Required	Set with `/plugin configure session-traces@respan`. Stored in your OS keychain.
Respan deployment	`platform`	`platform` or `enterprise`: the Respan your API key belongs to.

To stop tracing, disable or uninstall the plugin. To stop it for one project or run, set RESPAN_TRACING=false. The environment can only turn tracing off: the API key and where traces go come from your own settings, so a repository can’t send your sessions anywhere.

A project’s .claude/respan.json can set customer_id, span_name and workflow_name, and any other key is added to each turn’s metadata. Its base_url is ignored:

JSON


{
  "customer_id": "alice@example.com",
  "workflow_name": "claude-code",
  "team": "platform"
}

Performance

The plugin never makes Claude Code wait for Respan. It records each event in a background worker and sends finished spans after the turn ends, one request at a time. Measured on Claude Code 2.1.318, it adds about 0.2 ms to each streamed chunk and no measurable time to a turn.

If Respan is unreachable, the plugin keeps up to 8 MB of unsent traces and retries them later. Interactive sessions exit normally. A claude -p run waits up to a second at exit to send its last batch, and if Respan stops answering, the process can stay alive for up to 30 seconds after its result.

Limits

The plugin doesn’t run:

In WSL sessions in the Claude desktop app
In cloud sessions, unless the plugin is installed there
When your organization’s managed settings set allowManagedModsOnly or allowManagedHooksOnly, or turn off WebFetch

On a Team or Enterprise login, the system prompt and the context Claude Code adds to requests aren’t included.

Debugging

Check that the plugin is installed and its key is set:

Terminal


claude plugin list
claude plugin configure session-traces@respan

The second command lists each option without showing its value, as set or not set.

Issue	Solution
No traces appearing	Traces go to the project your API key belongs to. Check that `RESPAN_TRACING` isn’t `false`, and that you started a new session after setting the key.
`hooks module did not load ... Respan API Key is required`	Set the key with `/plugin configure session-traces@respan`.
`Respan rejected the API key` in the conversation	The key is invalid or revoked, or Respan deployment doesn’t match it.
Each turn appears twice	The old hook is still installed and running without the plugin. Remove the old hook.

For more detail, start Claude Code with claude --debug-file <path> and search the log for session-traces. Each export appears as a $.http.fetch (session-traces) line with its HTTP status.

Gateway

See Claude Code gateway setup to route this integration through the Respan gateway.