Skip to main content
OpenCode is an open-source coding agent you run in your terminal. The Catalyst OpenCode plugin records those coding sessions so you can review what the agent did: model calls, tool calls, token usage, cost, finish reasons, errors, prompts, responses, and tool payloads. This page is for observing a coding tool you use. To trace an agent or application you build, start with the Tracing Quickstart and the SDK integrations.
OpenCode installs npm plugins automatically from your opencode.json; you do not need to add this package to your app’s dependencies.

​
Install

Add the plugin to your OpenCode config, either in your project opencode.json or globally at ~/.config/opencode/opencode.json.
opencode.json

​
Configure

Opt in with your inference.net API key. INFERENCE_API_KEY alone never turns recording on (many environments export it for gateway calls), so pair it with TRACE_TO_INFERENCE=true.
Then use OpenCode as usual.

​
What Gets Recorded

Every turn, meaning one prompt and the agent’s response to it, becomes a trace in Catalyst. Spans carry the OpenCode session.id, so all turns from the same coding session can be grouped together.
  • The AGENT root span records session id, service identity, call counts, stop reason, and error status.
  • LLM spans record model/provider details, finish reason, prompt/cache/completion/reasoning tokens, and cost.
  • TOOL spans record shell, file, and MCP tool calls with 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.
Use these traces to audit what a session did, debug failed turns, compare how models behave on similar tasks, or track coding-agent cost. Turn on content redaction when you only need metadata and timing.

​
Configuration Reference

The plugin uses the same env-var convention as the TypeScript and Python tracing SDKs.

​
Local Collector

To export to a local collector without an auth token, set both an explicit endpoint and 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.

​
Troubleshooting

If no traces appear, check:
  • TRACE_TO_INFERENCE=true and INFERENCE_API_KEY are set in the environment that launches OpenCode.
  • INFERENCE_SERVICE_NAME is the value you are filtering for in the dashboard.
  • INFERENCE_OTLP_ENDPOINT is https://telemetry.inference.net unless you are intentionally using a custom collector.
  • OpenCode has restarted after you added the plugin to opencode.json.