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
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@inference/trace-opencode"]
}

​
Configure

Set your Catalyst OTLP token. Recording turns on automatically when the token is present. 
export CATALYST_OTLP_TOKEN="<your-token>"
export CATALYST_SERVICE_NAME="my-opencode"
Then use OpenCode as usual. 
opencode run "add a health check endpoint and a test for it"

​
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 CATALYST_REDACT_CONTENT=true to keep spans metadata-only. 
Turn (AGENT, session.id=ses_...)
  anthropic/claude-...  (LLM: tokens, cache, finish reason, cost)
  bash: ...             (TOOL: name, timing, status)
  read: file.ts         (TOOL)
  anthropic/claude-...  (LLM: final reply)
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 Catalyst tracing env-var convention as the TypeScript and Python tracing SDKs.
Environment variableDefaultDescription
CATALYST_OTLP_TOKEN-Catalyst ingest token. Recording starts when this is set.
CATALYST_OTLP_ENDPOINThttps://telemetry.inference.netOTLP/HTTP trace ingest endpoint.
CATALYST_SERVICE_NAMEopencodeStable OTel service.name, also used as the OpenCode agent id.
TRACE_TO_CATALYSTon when a token is setSet false to disable. Set true only for tokenless custom collectors with an explicit non-hosted endpoint.
CATALYST_REDACT_CONTENTfalseSet 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_DEBUGfalseVerbose plugin logging through OpenCode’s log API.

​
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.

​
Troubleshooting

If no traces appear, check:
  • CATALYST_OTLP_TOKEN is set in the environment that launches OpenCode.
  • CATALYST_SERVICE_NAME is the value you are filtering for in Catalyst.
  • CATALYST_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.