> ## Documentation Index
> Fetch the complete documentation index at: https://arize-ax.mintlify.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Claude Code

> Trace Claude Code CLI and Agent SDK sessions, tool usage, and token costs in Arize AX using the Arize Coding Harness Tracing.

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

[Claude Code](https://code.claude.com/docs/en/overview) is Anthropic's agentic coding tool that lives in your terminal. The [Arize Coding Harness Tracing](https://github.com/Arize-ai/coding-harness-tracing) instruments sessions using 16 hook events and sends [OpenInference](https://github.com/Arize-ai/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](https://app.arize.com/auth/join) and get your Space ID and API Key:

1. Log in at [app.arize.com](https://app.arize.com)
2. Click **Settings** and copy the **Space ID**
3. Open the **API Keys** tab and create or copy an API key

## Install

### Claude Code Marketplace

```bash theme={null}
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](#configuration)).

### Curl installer

**macOS / Linux:**

```bash theme={null}
curl -sSL https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.sh | bash -s -- claude
```

**Windows (PowerShell):**

```powershell theme={null}
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

```bash theme={null}
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)

```json theme={null}
{
  "env": {
    "PHOENIX_ENDPOINT": "http://localhost:6006",
    "ARIZE_PROJECT_NAME": "claude-code",
    "ARIZE_TRACE_ENABLED": "true"
  }
}
```

### Arize AX (cloud)

```json theme={null}
{
  "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:

```json theme={null}
{
  "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`

<Frame caption="Claude Code turns grouped together in a single session view">
  <img src="https://storage.googleapis.com/arize-assets/doc-images/claude-session.png" alt="Claude Code session view in Arize AX showing multiple traces grouped by session ID" />
</Frame>

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

<Frame caption="Detailed trace view for a Claude Code turn">
  <img src="https://storage.googleapis.com/arize-assets/doc-images/claude-trace.png" alt="Claude Code trace view in Arize AX showing the trace tree, inputs, outputs, and nested spans" />
</Frame>

### 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](https://platform.claude.com/docs/en/agent-sdk/overview) 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.

<Callout type="warning">
  You must use `ClaudeSDKClient`. The standalone `query()` function does not support hooks, so tracing will not work with it.
</Callout>

### 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`:

  ```bash theme={null}
  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`:

```json theme={null}
{
  "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](#configuration) apply here.

### 3. Wire the plugin into your app

Pass the plugin path and settings file to `ClaudeSDKClient`:

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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();
    ```
  </Tab>
</Tabs>

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

```python theme={null}
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](https://github.com/Arize-ai/coding-harness-tracing/blob/main/tracing/claude_code/README.md).

## Uninstall

**Marketplace install:**

```bash theme={null}
claude plugin uninstall claude-code-tracing@coding-harness-tracing
claude plugin marketplace remove Arize-ai/coding-harness-tracing
```

**Curl or local install:**

```bash theme={null}
curl -sSL https://raw.githubusercontent.com/Arize-ai/coding-harness-tracing/main/install.sh | bash -s -- uninstall claude
```

## Resources

<CardGroup>
  <Card icon="github" href="https://github.com/Arize-ai/coding-harness-tracing" title="Arize Coding Harness Tracing" horizontal />

  <Card icon="github" href="https://github.com/Arize-ai/openinference" title="OpenInference" horizontal />

  <Card icon="book-open" href="https://code.claude.com/docs/en/overview" title="Claude Code Documentation" horizontal />

  <Card icon="book-open" href="https://code.claude.com/docs/en/plugins" title="Claude Code Plugins" horizontal />

  <Card icon="book-open" href="https://arize.com/blog/claude-md-best-practices-learned-from-optimizing-claude-code-with-prompt-learning/" title="CLAUDE.md: Best Practices for Optimizing Claude Code with Prompt Learning" horizontal />
</CardGroup>