Claude Code → Arize Phoenix observability

Traces every Claude Code session on a machine into a local Phoenix instance: prompts, turns, tool calls, subagents and token counts.

The stock Arize harness installs but does not work end-to-end on Windows, and groups every repository into a single project. This skill installs it and applies the fixes that make it actually deliver spans.

What you get

• Global: hooks live in ~/.claude/settings.json, so every project is traced, not just the one you set it up in.
• Per-directory projects: each working directory becomes its own Phoenix project, named after the directory.
• Readable turns: Turn 3: fix the login redirect instead of Turn 1.

Fresh setup

Requires Docker and git. Python 3.9+ to run the scripts.

python scripts/setup.py

Idempotent — it is also the repair command. Then open a new Claude Code session and check http://localhost:6006/projects.

Against an existing or remote Phoenix:

python scripts/setup.py --skip-phoenix --endpoint http://phoenix.internal:6006

Diagnosing "I see no traces"

python scripts/doctor.py --smoke

Checks each layer in the order it fails and, with --smoke, drives the real hook binaries end-to-end and confirms a span lands (then deletes the probe project).

Work top-down — the four causes below are ranked by how often they are the answer, and each one produces zero or partial traces with no obvious error.

1. Hook paths with backslashes (Windows) — silent total failure

Symptom: UserPromptSubmit hook error / Failed with non-blocking status code: C:Usersyou.arizeharness...exe: command not found.

Claude Code runs hooks through bash, which eats \ as an escape character, so C:\Users\you\...\arize-hook-stop.exe becomes C:Usersyou...exe. Every hook no-ops; tracing looks installed and records nothing.

python scripts/fix_settings.py

The installer rewrites native paths every time it runs — re-run this after any install.sh / install.bat.

2. Phoenix too old — every span 405s

Symptom: no project ever appears; log shows Phoenix send failed: HTTP 405: Method Not Allowed.

The harness POSTs to /v1/projects/{id}/spans, which was GET-only in older Phoenix builds. A cached :latest image can be a year old.

python scripts/phoenix_up.py     # pulls, recreates, verifies the ingest route

Data lives in the phoenix_data volume, so recreating the container keeps it. Note Phoenix rejects JSON OTLP on /v1/traces with 415 — that is not a fallback.

3. Non-ASCII crash — partial traces

Symptom: a project exists but with holes; log shows 'charmap' codec can't decode byte 0x9d.

Python defaults to cp1252 on Windows, so any turn containing an emoji, arrow or curly quote crashes the hook. Plain-ASCII turns trace fine — which is exactly why the gaps look random. Fixed at two independent layers (PYTHONUTF8=1 in settings, plus UTF-8 pinned in the source):

python scripts/fix_settings.py && python scripts/patch_harness.py

4. Nothing wrong — you are waiting for a delay that does not exist

Sends are synchronous; each hook POSTs its span immediately. A span not in Phoenix within a second or two is not late, it is gone, and the reason is in ~/.arize/harness/logs/claude-code.log. That log is written only on error, so empty means healthy.

cat ~/.arize/harness/logs/claude-code.log

Is a session being traced at all? A live session writes a state file:

ls ~/.arize/harness/state/claude-code/

After upgrading the harness

The two behaviour patches edit a third-party repo, so git pull in ~/.arize/harness drops them:

python scripts/patch_harness.py   # re-apply + reinstall
python scripts/fix_settings.py    # re-fix hook paths

patch_harness.py --check reports status without changing anything. If upstream has moved, it reports anchor-drift and refuses rather than corrupting the file — re-derive the edit from references/patches.md.

Configuration

Gotchas that cost real time

• The harness venv is not an editable install. Hooks import a copy under venv/Lib/site-packages. Editing the repo source changes nothing until pip install . is re-run — patch_harness.py does this for you. Testing with python -c from the repo root imports the source and will appear to work while the real hooks still run old code.
• Two Stop rendering paths exist. The event-graph path (CHAIN turn + LLM/TOOL children) only runs when the transcript has new lines past trace_start_line; otherwise it falls back to a single legacy LLM span. Both are patched.
• Directories sharing a basename merge into one project (two different backend/ folders). Use PHOENIX_PROJECT to disambiguate.
• Hooks are not snapshotted at session start — edits take effect on the next hook event, though a fresh session is the reliable way to confirm.

Reference

• references/patches.md — what each patch changes and why a config-only solution is impossible
• references/architecture.md — how a span travels from keystroke to Phoenix