> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inference.net/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode Traces

> Record traces of your own OpenCode coding sessions to Catalyst.

[OpenCode](https://opencode.ai) 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](/integrations/traces/quickstart)
and the SDK integrations.

<Info>
  OpenCode installs npm plugins automatically from your `opencode.json`; you do
  not need to add this package to your app's dependencies.
</Info>

## Install

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

```json opencode.json theme={"system"}
{
  "$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.

```bash theme={"system"}
export CATALYST_OTLP_TOKEN="<your-token>"
export CATALYST_SERVICE_NAME="my-opencode"
```

Then use OpenCode as usual.

```bash theme={"system"}
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.

```text theme={"system"}
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 variable           | 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.                                                            |

### Local Collector

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

```bash theme={"system"}
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`.