@inference/trace-opencode

Automatically trace OpenCode coding sessions to Catalyst by Inference.net.

Each user turn becomes an OpenInference-shaped trace: an AGENT root span with child LLM spans for model calls and TOOL spans for shell, file, and MCP tool executions. Spans carry the OpenCode session.id so Catalyst can group a whole coding session together.

This package is in beta. APIs may change before 1.0.

Quick Start

1. Add the plugin to your OpenCode config (opencode.json, or ~/.config/opencode/opencode.json):

   {
     "$schema": "https://opencode.ai/config.json",
     "plugin": ["@inference/trace-opencode"]
   }

2. Set your Catalyst OTLP token. OpenCode installs the plugin from npm on its next launch, so you do not need to run npm install.

   export CATALYST_OTLP_TOKEN="<your-token>"
   export CATALYST_SERVICE_NAME="my-opencode"

3. Run OpenCode as usual:

   opencode run "refactor the auth module"

Tracing turns on automatically when CATALYST_OTLP_TOKEN is present. View the result in Catalyst at inference.net, grouped by service name and session id.

What Gets Captured

Per turn, the plugin emits:

• AGENT root span: session.id, service/agent identity, call counts, stop reason, and error status.
• LLM spans: model name, provider, finish reason, token usage including prompt-cache read/write and reasoning tokens, and cost.
• TOOL spans: tool name, call id, timing, and error status.

By default, spans include prompts, model output, tool arguments, and tool output. Set CATALYST_REDACT_CONTENT=true to keep spans metadata-only.

OpenTelemetry spans are immutable once ended and are only exported at that moment. A single session-long root span would be invisible until the session closed and could be lost if the process exited early. This plugin opens one fresh trace per turn and relies on session.id grouping to present the whole session in Catalyst.

Configuration

The plugin is configured with environment variables only.

| Env var | Default | Description | | --- | --- | --- | | CATALYST_OTLP_TOKEN | - | Catalyst ingest token. Recording starts when this is set. | | CATALYST_OTLP_ENDPOINT | https://telemetry.inference.net | OTLP/HTTP trace ingest endpoint. | | CATALYST_SERVICE_NAME | opencode | Stable OTel service.name, also used as the OpenCode agent id. | | TRACE_TO_CATALYST | on when a token is set | Set false to disable. Set true only for tokenless custom collectors with an explicit non-hosted endpoint. | | CATALYST_REDACT_CONTENT | false | Set true to keep prompts, model outputs, tool arguments, and tool outputs off traces. | | CATALYST_ADDITIONAL_METADATA | - | JSON object attached to each turn's metadata. | | CATALYST_DEBUG | false | Verbose plugin logging through OpenCode's log API. |

Earlier beta builds documented CATALYST_API_KEY, CATALYST_PROJECT, and catalyst.json. Those names are no longer read. Use CATALYST_OTLP_TOKEN, CATALYST_SERVICE_NAME, and environment variables instead.

If you installed an earlier beta, a bare reinstall can leave OpenCode's @latest plugin cache pinned to the old package. Install an explicit version to force a fresh cache entry:

opencode plugin @inference/[email protected] --force

To keep using the unversioned package name, remove the stale cache entry first:

rm -rf ~/.cache/opencode/packages/@inference/trace-opencode@latest
opencode plugin @inference/trace-opencode --force

Local Collector

To export to a local collector without an auth token, set both an explicit endpoint and TRACE_TO_CATALYST=true:

export CATALYST_OTLP_ENDPOINT="http://localhost:4318"
export TRACE_TO_CATALYST=true

Privacy

By default the plugin records prompts, model output, file content read or written by tools, and shell command output. Set CATALYST_REDACT_CONTENT=true when you want metadata-only traces.

How It Works

The plugin subscribes to OpenCode's plugin hooks and event bus (chat.message, message.updated, message.part.updated, tool.execute.before, tool.execute.after, session.idle, and session.error). It reconstructs spans in memory, exports them over OTLP/HTTP with @inference/tracing, and disables automatic SDK patching to avoid duplicate spans inside OpenCode.

License

MIT