Trace OpenCode sessions

Capture OpenCode sessions, assistant turns, tool calls, and subagent activity in LangSmith.

The @langchain/langsmith-opencode plugin sends OpenCode session traces to LangSmith. Use it to inspect agent turns, model metadata, token usage, tool calls, tool errors, attachments, and subagent activity from your OpenCode workflows.

Prerequisites

Before setting up tracing, ensure you have:

• OpenCode installed and configured.
• A LangSmith API key.
• Access to configure the OpenCode plugin key in opencode.json or ~/.config/opencode/opencode.json.

Install and enable the plugin

Add the plugin to your OpenCode configuration file. You can configure it locally in opencode.json or globally in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@langchain/langsmith-opencode"]
}

Enable tracing and provide your LangSmith API key before starting OpenCode:

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_PROJECT="opencode"

Run OpenCode as usual. The plugin sends completed user turns to the configured LangSmith project.

Configure tracing

Tracing is disabled by default. With TRACE_TO_LANGSMITH=true set, the plugin sends traces to LangSmith. You can also enable tracing with a LangSmith config file.

Environment variables

The plugin reads OpenCode-specific variables first, then falls back to the generic LangSmith SDK variables when available.

Variable	Required	Default	Description
TRACE_TO_LANGSMITH	Yes	false	Set to "true" to enable tracing.
LANGSMITH_OPENCODE_API_KEY	Conditional	-	LangSmith API key. Falls back to LANGSMITH_API_KEY. Required unless every replica provides its own API key.
LANGSMITH_OPENCODE_ENDPOINT	No	LangSmith SDK default	LangSmith API URL. Falls back to LANGSMITH_ENDPOINT.
LANGSMITH_OPENCODE_PROJECT	No	opencode	LangSmith project name. Falls back to LANGSMITH_PROJECT.
LANGSMITH_OPENCODE_METADATA	No	-	JSON object merged into root trace metadata.
LANGSMITH_OPENCODE_RUNS_ENDPOINTS	No	-	JSON array of replica destinations.

For example:

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_API_KEY="<your-langsmith-api-key>"
export LANGSMITH_PROJECT="opencode"
export LANGSMITH_OPENCODE_METADATA='{"team":"agents","environment":"dev"}'

Config files

Use .opencode/langsmith.json for project-level settings or ~/.config/opencode/langsmith.json for global defaults.

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "api_url": "https://api.smith.langchain.com",
  "project": "opencode",
  "metadata": {
    "team": "agents",
    "environment": "dev"
  }
}

Field	Required	Default	Description
enabled	Yes	false	Set to true to enable tracing from the config file.
api_key	Conditional	-	LangSmith API key. Required unless provided by environment variable or replicas.
api_url	No	LangSmith SDK default	LangSmith API URL, usually https://api.smith.langchain.com.
project	No	opencode	LangSmith project name.
metadata	No	-	Object merged into root trace metadata.
replicas	No	-	Additional LangSmith destinations to replicate traces to.

Keep config files that include API keys out of version control.

Trace to multiple destinations

Set replicas in langsmith.json or LANGSMITH_OPENCODE_RUNS_ENDPOINTS to send the same trace data to additional LangSmith workspaces or projects.

{
  "enabled": true,
  "api_key": "<your-langsmith-api-key>",
  "project": "opencode",
  "replicas": [
    {
      "api_url": "https://api.smith.langchain.com",
      "api_key": "<your-replica-langsmith-api-key>",
      "project": "opencode-replica",
      "updates": {
        "metadata": {
          "replica": true
        }
      }
    }
  ]
}

Replica objects support both snake_case and LangSmith SDK-style camelCase field names. snake_case is recommended in config files.

Field	Description
api_url / apiUrl	LangSmith API URL for the replica destination.
api_key / apiKey	API key for the destination workspace.
project / projectName	Project name in the destination workspace.
updates	Optional run fields to override on replicated runs, such as extra metadata.

What gets traced

The plugin listens to OpenCode chat and event hooks, aggregates each completed user turn, and submits it to LangSmith as a run tree.

• opencode.session root runs for completed user turns.
• opencode.assistant.turn child runs for assistant and model responses.
• Nested tool runs for tool calls, including inputs, outputs, errors, timing, and attachments when available.
• Subagent sessions nested under the parent tool call.
• Model name, provider, invocation parameters, token usage, and thread or session ID metadata.
• User messages, assistant messages, reasoning blocks, file parts, and system prompts associated with assistant turns.

Trace completion is based on OpenCode step-finish events. The plugin also flushes pending trace batches when the OpenCode server shuts down.

View traces in LangSmith

Open the configured LangSmith project and look for root runs named opencode.session. Each trace contains the user turn as the root input and assistant responses, tool calls, and subagent traces as child runs. The plugin stores the OpenCode session ID as thread_id metadata, so you can filter or group related OpenCode turns in LangSmith.

Troubleshooting

If traces do not appear in LangSmith:

• Confirm tracing is enabled with TRACE_TO_LANGSMITH=true or "enabled": true in config.
• Confirm the LangSmith API key is set in the same shell, project config, or global config used by OpenCode.
• Confirm the plugin package is installed where OpenCode can resolve it.
• Check the selected LangSmith project. If no project is configured, traces go to opencode.
• Restart OpenCode after changing opencode.json, langsmith.json, or environment variables.
• Make sure a user turn completes. The plugin does not send incomplete turns.

---

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.