Skip to main content
OpenCode is an open-source coding agent you run in your terminal. This plugin automatically records your OpenCode sessions to Catalyst so you can see what your coding agent actually did — the prompts it sent, the models it called, the tools it ran, and the tokens and cost each session spent. This is different from the other tracing integrations. Those instrument an agent or application you build so you can observe it in production. This records a coding tool you use: you don’t write or change any code, you install a plugin and your sessions show up in Catalyst.
Use this to observe your own OpenCode usage — reviewing sessions, debugging a tool call, or tracking model cost. To trace an agent you are building for your own users, start with the Quickstart and the SDK integrations instead.

​
Install

Add the plugin to your OpenCode config, either opencode.json in your project or ~/.config/opencode/opencode.json globally. OpenCode installs it from npm on the next launch.
opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@inference/trace-opencode"]
}

​
Configure

Set your Catalyst API key. Recording turns on automatically once a key is present. 
export CATALYST_API_KEY="sk-inf-..."
# optional: a stable project name to group your sessions under in Catalyst
export CATALYST_PROJECT="my-opencode"
Then use OpenCode as you normally would. Your next session is recorded for you. 
opencode run "add a health check endpoint and a test for it"

​
What gets recorded

Every turn — one prompt you send and the agent’s full response — becomes a trace in Catalyst, tagged with the OpenCode session id so all of a session’s turns stay grouped together. Each trace captures:
  • The prompt you sent and the agent’s final reply.
  • An LLM span for each model call in the turn, with token usage — including prompt-cache read and write and reasoning tokens — and the cost of the call.
  • A tool span for each bash, read, edit, and MCP tool call, with its arguments and output.
Turn (AGENT, session.id=ses_…)
├── anthropic/claude-…  (LLM — tokens, cache, cost)
├── bash: …             (TOOL — arguments, output, timing)
├── read: file.ts       (TOOL)
└── anthropic/claude-…  (LLM — final reply)
Use these traces to replay what a session did, debug a tool call that went wrong, compare how different models handle the same task, or see how much a session cost.

​
Configuration

Configure the plugin with environment variables or a catalyst.json file. Precedence, from lowest to highest, is built-in defaults, the global ~/.config/opencode/catalyst.json, the project .opencode/catalyst.json, then environment variables.
Environment variablecatalyst.json keyDefaultDescription
CATALYST_API_KEYapi_key—Catalyst ingest token. Recording starts when this is set.
TRACE_TO_CATALYSTtrace_to_catalyston when a key is setForce recording on or off.
CATALYST_OTLP_ENDPOINTendpointhttps://telemetry.inference.netOTLP/HTTP ingest endpoint.
CATALYST_PROJECTprojectopencodeProject name your sessions are grouped under.
CATALYST_REDACT_CONTENTredact_contentfalseRecord metadata only — models, tokens, cost, tool names, and timing.

​
Privacy

By default the plugin records full content, including your prompts, the model’s output, file contents it reads or writes, and shell command output. If you would rather keep that off your traces, set CATALYST_REDACT_CONTENT=true to record metadata only — models, tokens, cost, tool names, and timing.