Claude Code

Trace Claude Code CLI sessions, tool usage, and token costs with Arize AX for full observability.

Claude Code is Anthropic’s agentic coding tool that lives in your terminal. The Arize Coding Harness Tracing instruments sessions using 16 hook events and sends OpenInference spans to Arize AX or Phoenix. The plugin works with both the Claude Code CLI and the Claude Agent SDK.

Launch Arize AX

To get started, sign up for a free Arize AX account and get your Space ID and API Key:

Log in at app.arize.com
Click Settings and copy the Space ID
Open the API Keys tab and create or copy an API key

Install

Claude Code Marketplace

claude plugin marketplace add Arize-ai/coding-harness-tracing
claude plugin install claude-code-tracing@coding-harness-tracing

The marketplace flow registers the hooks but skips the interactive wizard, so backend credentials and content-logging preferences must be set directly in ~/.claude/settings.json under env (see Configuration).

Curl installer

macOS / Linux:

curl -sSL https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.sh | bash -s -- claude

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.bat -OutFile $env:TEMP\install.bat
& $env:TEMP\install.bat claude

The installer prompts for your backend (Phoenix or Arize AX) and project name, writes credentials to ~/.arize/harness/config.yaml, and registers the hooks in ~/.claude/settings.json.

Local clone

git clone https://github.com/Arize-ai/coding-harness-tracing.git
cd coding-harness-tracing
./install.sh claude        # macOS / Linux
install.bat claude         # Windows

Configuration

The curl and local installers write credentials to ~/.arize/harness/config.yaml. Environment variables in ~/.claude/settings.json take precedence and are required for the marketplace install path.

Phoenix (self-hosted)

{
  "env": {
    "PHOENIX_ENDPOINT": "http://localhost:6006",
    "ARIZE_PROJECT_NAME": "claude-code",
    "ARIZE_TRACE_ENABLED": "true"
  }
}

Arize AX (cloud)

{
  "env": {
    "ARIZE_API_KEY": "<your-api-key>",
    "ARIZE_SPACE_ID": "<your-space-id>",
    "ARIZE_PROJECT_NAME": "claude-code",
    "ARIZE_TRACE_ENABLED": "true"
  }
}

Redaction controls

Each ARIZE_LOG_* flag accepts "true" or "false" and defaults to "true". Set to "false" to opt out per category:

{
  "env": {
    "ARIZE_LOG_PROMPTS": "false",
    "ARIZE_LOG_TOOL_DETAILS": "false",
    "ARIZE_LOG_TOOL_CONTENT": "false"
  }
}

Flag	Redacts
`ARIZE_LOG_PROMPTS`	User prompt and assistant response text
`ARIZE_LOG_TOOL_DETAILS`	Tool names and arguments
`ARIZE_LOG_TOOL_CONTENT`	Tool call output content

Observe

Now that you have tracing set up, all Claude Code sessions stream to your Arize AX account for observability and evaluation. You’ll see:

Turn traces — each conversation turn (user prompt → assistant response)
LLM spans — Claude’s responses with model info and token counts
Tool spans — nested spans for each tool call with inputs, outputs, and duration
Subagent spans — activity from any subagents Claude spawns
Session grouping — all turns from the same session grouped by session_id

Claude Code session view in Arize AX showing multiple traces grouped by session ID

Drill into any turn trace to inspect the full span tree, including model generations, tool calls, and subagent activity.

Claude Code trace view in Arize AX showing the trace tree, inputs, outputs, and nested spans

Hooks Captured

Hook	Span Kind	Description
`SessionStart`	CHAIN	Session initialized, trace/tool counters reset
`UserPromptSubmit`	CHAIN	User prompt captured (also lazy-inits session for SDK)
`UserPromptExpansion`	—	Stashes slash command metadata to attach to the next turn span
`PreToolUse`	TOOL	Tool invocation started, records tool name and input
`PostToolUse`	TOOL	Tool invocation completed, records output and duration
`PostToolUseFailure`	TOOL	Tool invocation failed, records error attributes
`Stop`	LLM	Model response completed with input/output values
`StopFailure`	LLM	Turn failed before completion, emits a span with `error.type` / `error.message`
`SubagentStart`	—	Records subagent start time and prompt keyed by `agent_id`
`SubagentStop`	CHAIN	Subagent response completed
`PreCompact`	—	Records compaction start time and trigger
`PostCompact`	CHAIN	Compaction completed, emits a span when it fires inside a turn
`PermissionRequest`	CHAIN	Permission prompt for tool use
`PermissionDenied`	CHAIN	Auto-mode tool denial recorded inside the current turn
`Notification`	CHAIN	System notification event
`SessionEnd`	CHAIN	Session teardown, state file cleanup

Hooks marked — don’t emit their own span — they stash state that an adjacent hook (Turn, tool, or compaction) attaches when it fires.

Agent SDK Setup

The tracing plugin also works with the Claude Agent SDK in both Python and TypeScript. The SDK loads the plugin locally — no marketplace install is required — but the setup must be done in your application code before the SDK session starts, so the agent cannot configure it at runtime.

You must use ClaudeSDKClient. The standalone query() function does not support hooks, so tracing will not work with it.

1. Locate the plugin

The plugin path depends on how you installed the harness:

Installed via the Claude Code CLI marketplace: the plugin is cached at ~/.claude/plugins/cache/coding-harness-tracing/claude-code-tracing/1.0.0.
Installed via the curl or local installer: the plugin lives at ~/.arize/harness/tracing/claude_code.
Not installed: clone the repo into your project — the plugin path is ./coding-harness-tracing/claude-code-tracing:
```
git clone https://github.com/Arize-ai/coding-harness-tracing.git
```

2. Create a settings file

The SDK spawns a Claude Code subprocess that does not inherit your shell environment, so tracing env vars must be passed through a settings file referenced from ClaudeAgentOptions:

{
  "env": {
    "ARIZE_TRACE_ENABLED": "true",
    "ARIZE_API_KEY": "<your-api-key>",
    "ARIZE_SPACE_ID": "<your-space-id>",
    "ARIZE_PROJECT_NAME": "claude-code"
  }
}

For Phoenix, replace the Arize AX keys with PHOENIX_ENDPOINT (and optional PHOENIX_API_KEY). The same ARIZE_LOG_* redaction flags from Configuration apply here.

3. Wire the plugin into your app

Pass the plugin path and settings file to ClaudeSDKClient:

Python
TypeScript

from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient

PLUGIN_PATH = "./coding-harness-tracing/claude-code-tracing"  # or your install path

options = ClaudeAgentOptions(
    plugins=[{"type": "local", "path": PLUGIN_PATH}],
    settings="./settings.local.json",
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Your prompt here")
    async for message in client.receive_response():
        print(message)

import { ClaudeSDKClient } from "@anthropic-ai/claude-agent-sdk";

const PLUGIN_PATH = "./coding-harness-tracing/claude-code-tracing"; // or your install path

const client = new ClaudeSDKClient({
  plugins: [{ type: "local", path: PLUGIN_PATH }],
  settings: "./settings.local.json",
});

await client.connect();
await client.query("Your prompt here");
for await (const message of client.receiveResponse()) {
  console.log(message);
}
await client.close();

If you installed via the curl or local installer, the harness ships a Python convenience helper that returns a pre-configured ClaudeAgentOptions (plugin path + setting_sources=["user"] so user-level Claude settings are honored):

from tracing.claude_code.agent_sdk import claude_options

async with ClaudeSDKClient(options=claude_options()) as client:
    ...

Validate

Add "ARIZE_DRY_RUN": "true" to your settings file to verify hooks fire without sending data, and tail ~/.arize/harness/logs/claude-code.log to confirm activity.

Hook parity

SDK	Coverage
TypeScript	Full parity — all 16 hooks fire, including `SessionStart`, `Notification`, `PermissionRequest`, and `SessionEnd`.
Python	`SessionStart`, `SessionEnd`, `Notification`, and `PermissionRequest` are not available. Session state is lazily initialized on the first `UserPromptSubmit`; core tracing (LLM, tool, and subagent spans) still works fully.

Reference

For the full list of environment variables, default file paths, and troubleshooting steps, see the Claude Code tracing README.

Uninstall

Marketplace install:

claude plugin uninstall claude-code-tracing@coding-harness-tracing
claude plugin marketplace remove Arize-ai/coding-harness-tracing

Curl or local install:

curl -sSL https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.sh | bash -s -- uninstall claude

Launch Arize AX

Install

Claude Code Marketplace

Curl installer

Local clone

Configuration

Phoenix (self-hosted)

Arize AX (cloud)

Redaction controls

Observe

Hooks Captured

Agent SDK Setup

1. Locate the plugin

2. Create a settings file

3. Wire the plugin into your app

Validate

Hook parity

Reference

Uninstall

Resources

Arize Coding Harness Tracing

OpenInference

Claude Code Documentation

Claude Code Plugins

CLAUDE.md: Best Practices for Optimizing Claude Code with Prompt Learning

​Launch Arize AX

​Install

​Claude Code Marketplace

​Curl installer

​Local clone

​Configuration

​Phoenix (self-hosted)

​Arize AX (cloud)

​Redaction controls

​Observe

​Hooks Captured

​Agent SDK Setup

​1. Locate the plugin

​2. Create a settings file

​3. Wire the plugin into your app

​Validate

​Hook parity

​Reference

​Uninstall

​Resources

Arize Coding Harness Tracing

OpenInference

Claude Code Documentation

Claude Code Plugins

CLAUDE.md: Best Practices for Optimizing Claude Code with Prompt Learning

Launch Arize AX

Install

Claude Code Marketplace

Curl installer

Local clone

Configuration

Phoenix (self-hosted)

Arize AX (cloud)

Redaction controls

Observe

Hooks Captured

Agent SDK Setup

1. Locate the plugin

2. Create a settings file

3. Wire the plugin into your app

Validate

Hook parity

Reference

Uninstall

Resources