Skip to main content
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 Agent Kit instruments sessions using 9 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

To get started, sign up for a free Arize account and get your Space ID and API Key:
  1. Log in at 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 plugin marketplace add Arize-ai/arize-agent-kit
claude plugin install claude-code-tracing@arize-agent-kit

​
Curl installer

curl -fsSL https://raw.githubusercontent.com/Arize-ai/arize-agent-kit/main/install.sh | bash
The installer detects Claude Code and guides you through configuration.

​
Manual (Agent SDK)

Clone the repository and point your Agent SDK project at the plugin directory: 
git clone https://github.com/Arize-ai/arize-agent-kit.git
# In your SDK config, set the plugin path to:
#   /path/to/arize-agent-kit/claude-code-tracing

​
Configuration

Run the interactive setup after installation: 
bash claude-code-tracing/scripts/setup.sh
The setup script will:
  1. Ask whether to store tracing env vars globally in ~/.claude/settings.json or project-locally in .claude/settings.local.json
  2. Ask which backend to configure: Phoenix or Arize AX
  3. Write the required env vars into the selected Claude settings file
  4. Optionally add ARIZE_USER_ID for span attribution
Or configure manually by adding environment variables to either ~/.claude/settings.json or .claude/settings.local.json:

​
Phoenix (self-hosted)

{
  "env": {
    "PHOENIX_ENDPOINT": "http://localhost:6006",
    "ARIZE_TRACE_ENABLED": "true"
  }
}
Requires: jq, curl. No Python needed.

​
Arize AX (cloud)

{
  "env": {
    "ARIZE_API_KEY": "<your-api-key>",
    "ARIZE_SPACE_ID": "<your-space-id>",
    "ARIZE_TRACE_ENABLED": "true"
  }
}
Requires: jq, curl, Python 3 with opentelemetry-proto and grpcio: 
pip install opentelemetry-proto grpcio

​
Restart Claude Code

Restart Claude Code for tracing to take effect: 
claude

​
Observe

Now that you have tracing setup, all Claude Code sessions will be streamed to your Arize 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 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 showing the trace tree, inputs, outputs, and nested spans

​
Hooks Captured

HookSpan KindDescription
SessionStartCHAINSession initialized, trace/tool counters reset
UserPromptSubmitCHAINUser prompt captured (also lazy-inits session for SDK)
PreToolUseTOOLTool invocation started, records tool name and input
PostToolUseTOOLTool invocation completed, records output and duration
StopLLMModel response completed with input/output values
SubagentStopLLMSubagent response completed
NotificationCHAINSystem notification event
PermissionRequestCHAINPermission prompt for tool use
SessionEndCHAINSession teardown, state file cleanup

​
Agent SDK Compatibility

The plugin works with the Claude Agent SDK (Python) with one difference: the SDK does not fire a SessionStart event. The UserPromptSubmit hook performs lazy session initialization when it detects no prior session state.

​
Environment Variables

VariableRequiredDefaultDescription
ARIZE_TRACE_ENABLEDNotrueEnable or disable tracing
ARIZE_API_KEYFor AX-Arize AX API key
ARIZE_SPACE_IDFor AX-Arize AX space ID
ARIZE_OTLP_ENDPOINTNootlp.arize.com:443OTLP gRPC endpoint (on-prem Arize)
PHOENIX_ENDPOINTFor Phoenixhttp://localhost:6006Phoenix collector URL
PHOENIX_API_KEYNo-Phoenix API key (if auth enabled)
ARIZE_PROJECT_NAMENoWorking dir basenameProject name in Arize/Phoenix
ARIZE_USER_IDNo-User identifier added to all spans as user.id
ARIZE_DRY_RUNNofalsePrint spans to log instead of sending
ARIZE_VERBOSENofalseEnable verbose logging
ARIZE_LOG_FILENo/tmp/arize-claude-code.logLog file path (empty to disable)

​
Troubleshooting

ProblemFix
Spans not appearing in PhoenixVerify Phoenix is running (curl -s http://localhost:6006/healthz), check PHOENIX_ENDPOINT and ARIZE_TRACE_ENABLED
Spans not appearing in Arize AXCheck ARIZE_API_KEY and ARIZE_SPACE_ID, ensure Python deps (python3 -c "import opentelemetry; import grpc")
jq required errorInstall jq: brew install jq (macOS) or apt-get install jq (Linux)
No output in terminalHook stderr is discarded; check /tmp/arize-claude-code.log
Want to test without sendingSet ARIZE_DRY_RUN to "true"
Want verbose loggingSet ARIZE_VERBOSE to "true"
User ID not appearing on spansVerify ARIZE_USER_ID is set in .claude/settings.local.json under the env key
Session state issuesRemove stale state: rm -rf ~/.arize-claude-code/state_*.json

​
Uninstall

claude plugin remove arize-agent-kit

​
Resources