Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.langchain.com/llms.txt

Use this file to discover all available pages before exploring further.

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.
VariableRequiredDefaultDescription
TRACE_TO_LANGSMITHYesfalseSet to "true" to enable tracing.
LANGSMITH_OPENCODE_API_KEYConditional-LangSmith API key. Falls back to LANGSMITH_API_KEY. Required unless every replica provides its own API key.
LANGSMITH_OPENCODE_ENDPOINTNoLangSmith SDK defaultLangSmith API URL. Falls back to LANGSMITH_ENDPOINT.
LANGSMITH_OPENCODE_PROJECTNoopencodeLangSmith project name. Falls back to LANGSMITH_PROJECT.
LANGSMITH_OPENCODE_METADATANo-JSON object merged into root trace metadata.
LANGSMITH_OPENCODE_RUNS_ENDPOINTSNo-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"
  }
}
FieldRequiredDefaultDescription
enabledYesfalseSet to true to enable tracing from the config file.
api_keyConditional-LangSmith API key. Required unless provided by environment variable or replicas.
api_urlNoLangSmith SDK defaultLangSmith API URL, usually https://api.smith.langchain.com.
projectNoopencodeLangSmith project name.
metadataNo-Object merged into root trace metadata.
replicasNo-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.
FieldDescription
api_url / apiUrlLangSmith API URL for the replica destination.
api_key / apiKeyAPI key for the destination workspace.
project / projectNameProject name in the destination workspace.
updatesOptional 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.