Trace OpenCode terminal coding sessions, model calls, and tool usage in Phoenix.
Trace OpenCode terminal coding sessions, model calls, and tool usage with Phoenix for full observability.
Trace your OpenCode sessions in Phoenix with the coding-harness-tracing toolkit — every turn shows up as a trace, with the model call and every tool invocation captured as nested spans and grouped into its session. No application code changes required: the toolkit loads an in-process plugin and streams OpenInference spans to Phoenix.
The fastest way to get started with Phoenix is by signing up for a free Phoenix Cloud account. If you prefer, you can also run Phoenix in a notebook, self-host it, or use it directly from your terminal.Go to the settings page in your Phoenix instance to find your endpoint and API key. A self-hosted Phoenix defaults to http://localhost:6006; the API key is only required when auth is enabled.
The curl installer is the simplest — it runs a short wizard that saves your Phoenix credentials for you. Use a local clone if you’d rather run the installer from a checkout of the source.
The installer prompts for your backend — select Phoenix, then enter your endpoint and optional API key — and your project name, writes them to ~/.arize/harness/config.json, and copies the tracing plugin to ~/.config/opencode/plugin/arize-tracing.ts. OpenCode auto-discovers plugins from both the plugin/ and plugins/ directories under ~/.config/opencode/, so no opencode.json edit is required.
Credentials live in ~/.arize/harness/config.json. Environment variables override values in config.json and can be set in your shell profile so they apply to every OpenCode session.
export PHOENIX_ENDPOINT="http://localhost:6006"export PHOENIX_API_KEY="<your-api-key>" # optional, only if auth is enabledexport PHOENIX_PROJECT="opencode"export ARIZE_TRACE_ENABLED="true"
On the Phoenix backend, set the project name with PHOENIX_PROJECT (or PHOENIX_PROJECT_NAME); ARIZE_PROJECT_NAME is Arize-only and ignored here. ARIZE_TRACE_ENABLED is a backend-agnostic harness setting and keeps the ARIZE_ prefix regardless of destination.
If ARIZE_TRACE_ENABLED=false is set in your shell environment — for example, inherited from another harness’s configuration — tracing is silently disabled. Set ARIZE_TRACE_ENABLED=true before launching OpenCode, or unset the variable to fall back to the default of true.
OpenCode is architecturally different from the other coding agents in this repo. Extensions load as plugins inside OpenCode’s Bun runtime — there is no per-event subprocess. The integration has two pieces:
A TypeScript plugin shim at ~/.config/opencode/plugin/arize-tracing.ts that listens for message.updated and session.idle events, pulls the authoritative session snapshot via the OpenCode SDK, and pipes it to the reconciler.
A Python reconciler (arize-hook-opencode) that walks the snapshot and emits any new Turn, LLM, and TOOL spans, deduplicated by message ID and tool call ID. Spans are sent directly to Phoenix — no separate buffer or collector service is required.
Sub-agent and task sessions trace independently. OpenCode’s built-in task tool spawns sub-agents that each get their own sessionID. In v1, each sub-agent session produces its own independent trace; they are not linked back to the parent session’s trace.
