claude-code-tracing

Automatically trace Claude Code CLI or Agent SDK sessions to Arize AX (cloud) or Phoenix (self-hosted) using OpenInference spans for observability. Trigger custom bash scripts on 9 lifecycle events like SessionStart, PreToolUse, SessionEnd to enable event-driven automation.

Arize Claude Code Plugins

Official Claude Code plugins from Arize AI for enhanced observability and platform integration.

What's Included

This repository contains the following plugins:

claude-code-tracing — Automatic tracing of Claude Code sessions to Arize AX or Phoenix
arize-platform — Skills for managing projects, datasets, and working with the Arize AX CLI

Installation

Add the marketplace from repo owner/name:

claude plugin marketplace add Arize-ai/arize-claude-code-plugin

Then install the plugins:

claude plugin install claude-code-tracing@arize-claude-plugin
claude plugin install arize-platform@arize-claude-plugin

Claude Agent SDK

The tracing plugin works with the Claude Agent SDK (Python and TypeScript). Load it as a local plugin by pointing to the plugin directory.

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

Option A: Already installed via CLI (easiest)

If you already installed the plugin with claude plugin add, reference it from the CLI cache:

# Python
plugins=[{"type": "local", "path": "~/.claude/plugins/cache/arize-claude-plugin/claude-code-tracing/1.0.0"}]

// TypeScript
plugins: [{ type: "local", path: "~/.claude/plugins/cache/arize-claude-plugin/claude-code-tracing/1.0.0" }]

Tip: Check ~/.claude/plugins/installed_plugins.json for the exact path and version on your machine.

Option B: Clone the repo

If you haven't installed via the CLI, clone the repo into your project:

git clone https://github.com/Arize-ai/arize-claude-code-plugin.git

Then reference the plugin directory:

# Python
plugins=[{"type": "local", "path": "./arize-claude-code-plugin/plugins/claude-code-tracing"}]

// TypeScript
plugins: [{ type: "local", path: "./arize-claude-code-plugin/plugins/claude-code-tracing" }]

Make sure to also pass in the path to the settings.json file.

# Python
settings="./settings.local.json"

// TypeScript
settingSources: ["local"] // only .claude/settings.local.json

Full example

Python:

import asyncio
from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient


async def main():
    options = ClaudeAgentOptions(
        plugins=[{"type": "local", "path": "./arize-claude-code-plugin/plugins/claude-code-tracing"}],
        settings="./settings.local.json"
    )
    async with ClaudeSDKClient(options=options) as client:
        await client.query("PROMPT_GOES_HERE")
        async for message in client.receive_response():
            print(message)

asyncio.run(main())

TypeScript:

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

const client = new ClaudeSDKClient({
  plugins: [{ type: "local", path: "./arize-claude-code-plugin/plugins/claude-code-tracing" }],
  settingSources: ["local"],
});

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

Agent SDK Compatibility Notes

The plugin is fully compatible with the Agent SDK with some caveats:

TypeScript SDK — All 9 hooks are supported. Full feature parity with the CLI.
Python SDK — SessionStart, SessionEnd, Notification, and PermissionRequest hooks are not fired by the Python SDK. The plugin handles this gracefully:
- Session initialization happens lazily on the first UserPromptSubmit if SessionStart didn't fire
- Stale state files are garbage-collected periodically by the Stop hook
- Notification and permission request spans are simply not created (non-critical, informational only)