@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. Opt in to tracing with your inference.net API key. OpenCode installs the plugin from npm on its next launch, so you do not need to run npm install.

   export TRACE_TO_INFERENCE=true
   export INFERENCE_API_KEY="<your-inference-api-key>"
   export INFERENCE_SERVICE_NAME="my-opencode"

3. Run OpenCode as usual:

   opencode run "refactor the auth module"

Tracing turns on when TRACE_TO_INFERENCE=true is set together with INFERENCE_API_KEY. INFERENCE_API_KEY alone never enables tracing — many environments export it for gateway calls without meaning to record coding sessions. View the result 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 INFERENCE_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 | | --- | --- | --- | | INFERENCE_API_KEY | - | inference.net API key used as the ingest bearer token. Requires TRACE_TO_INFERENCE=true to enable recording. | | INFERENCE_OTLP_ENDPOINT | https://telemetry.inference.net | OTLP/HTTP trace ingest endpoint. | | INFERENCE_SERVICE_NAME | opencode | Stable OTel service.name, also used as the OpenCode agent id. | | TRACE_TO_INFERENCE | off | Set true to enable with INFERENCE_API_KEY, or with a tokenless custom collector via an explicit non-hosted endpoint. Set false to force-disable. | | INFERENCE_REDACT_CONTENT | false | Set true to keep prompts, model outputs, tool arguments, and tool outputs off traces. | | INFERENCE_ADDITIONAL_METADATA | - | JSON object attached to each turn's metadata. | | INFERENCE_DEBUG | false | Verbose plugin logging through OpenCode's log API. |

Earlier beta builds documented other names and a catalyst.json config file. Those are no longer read; use the environment variables above.

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_INFERENCE=true:

export INFERENCE_OTLP_ENDPOINT="http://localhost:4318"
export TRACE_TO_INFERENCE=true

Privacy

By default the plugin records prompts, model output, file content read or written by tools, and shell command output. Set INFERENCE_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