@langchain/langsmith-opencode

Trace OpenCode sessions to LangSmith so you can inspect agent turns, tool calls, model metadata, token usage, and subagent activity within LangSmith.

What It Does

@langchain/langsmith-opencode is an OpenCode plugin that listens to OpenCode chat and event hooks, aggregates each user turn, and posts it to LangSmith as a run tree:

• opencode.session root runs for each completed user turn.
• opencode.assistant.turn child runs for assistant/model responses.
• Tool calls as nested tool runs with inputs, outputs, errors, timing, and attachments when available.
• Subagent sessions as nested traces under the parent tool call.
• LangSmith metadata for model name, provider, invocation parameters, token usage, and thread/session ID.

Quick Start

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",
  "plugins": ["@langchain/langsmith-opencode"]
}

Set your LangSmith credentials before starting OpenCode:

export LANGSMITH_API_KEY="lsv2_pt_..."
export TRACE_TO_LANGSMITH="true"

Then run OpenCode as usual. Completed turns will appear in the configured LangSmith project.

LangSmith API keys

To create an API key:

1. Go to smith.langchain.com.
2. Sign in or create an account.
3. Open Settings -> API Keys.
4. Click Create API Key.
5. Copy the key and set it as LANGSMITH_API_KEY, LANGSMITH_OPENCODE_API_KEY, or api_key in a local config file.

Configuration

Tracing is disabled by default. Enable it with TRACE_TO_LANGSMITH=true or with a config file.

Environment Variables

The plugin accepts OpenCode-specific LangSmith 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	No*	-	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.
LANGSMITH_OPENCODE_REDACT	No	true	Redact detected secrets before upload. Set to false or 0 to disable.
LANGSMITH_OPENCODE_REDACT_EXTRA	No	-	JSON array of extra { pattern, replace } redaction rules. pattern is a case-sensitive regex.

Example:

export TRACE_TO_LANGSMITH="true"
export LANGSMITH_API_KEY="lsv2_pt_..."
export LANGSMITH_PROJECT="opencode"
export LANGSMITH_OPENCODE_METADATA='{"team":"agents","environment":"dev"}'

Config Files

Use .opencode/langsmith.json in your project for per-project settings, or ~/.config/opencode/langsmith.json for global defaults.

Field	Required	Default	Description
enabled	Yes	false	Set to true to enable tracing from the config file.
api_key	No*	-	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	-	Array of additional LangSmith destinations to replicate traces to.
redact	No	true	Redact detected secrets before upload. Set to false to disable.
redact_extra_rules	No	-	Array of extra { pattern, replace } redaction rules. pattern is a case-sensitive regex.

{
  "enabled": true,
  "api_key": "lsv2_pt_...",
  "api_url": "https://api.smith.langchain.com",
  "project": "opencode",
  "metadata": {
    "team": "agents",
    "environment": "dev"
  },
  "replicas": [
    {
      "api_url": "https://api.smith.langchain.com",
      "api_key": "lsv2_pt_...",
      "project": "opencode-replica",
      "updates": {
        "metadata": {
          "replica": true
        }
      }
    }
  ]
}

api_key is required unless the API key is provided by environment variable. Keep config files with API keys out of version control.

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

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

What Gets Traced

The plugin captures OpenCode session events and converts them into LangSmith-compatible chat messages and run metadata.

Captured content includes:

• User messages, assistant messages, reasoning blocks, and file parts.
• Tool calls, tool results, tool errors, and tool attachments.
• System prompts associated with assistant turns.
• Model and provider metadata from OpenCode.
• Token usage from completed model steps when OpenCode provides it.
• Session history so each assistant turn has the relevant chat context.

Trace completion is based on OpenCode step-finish events. When OpenCode disposes the server instance, the plugin flushes pending LangSmith trace batches.

Trace Metadata Contract (coding-agent-v1)

Every run sets a shared, versioned coding-agent metadata block on run.extra.metadata, so traces from any LangSmith coding-agent integration are identifiable, groupable, queryable, and attributable with the same stable keys. The block is built once on the root and propagates to child runs (langsmith ≥ 0.6.0 createChild).

Required on every run:

Key	Value (this integration)
ls_agent_purpose	"coding" (fixed)
ls_agent_type	"root" or "subagent" based on owning session
ls_integration	"opencode" (fixed)
ls_agent_runtime	"OpenCode" (fixed)
thread_id	root session id (sub-sessions inherit the root's id)
ls_trace_schema_version	"coding-agent-v1" (fixed)

Required where the runtime exposes them:

Key	Source
ls_integration_version	this plugin's package.json version
ls_agent_runtime_version	OpenCode version from the session info
turn_id	the turn's user message id
turn_number	1-based index of the user turn within the session
repository_url / repository_provider / repository_name	parsed from the git origin remote in cwd
git_branch / git_commit_sha	git CLI, run in cwd
cwd	session working directory (process.cwd() fallback)

Contextual (emitted only where known):

Key	Notes
local_username	OS username (PII-sensitive)
ls_subagent_id	sub-session id — subagent runs only
ls_subagent_type	sub-session agent name (e.g. general) — subagent runs only

Notes:

• Unknown values are omitted, never set to null — a present-but-null key counts as a contract leak.
• Scope-restricted keys do not propagate to runs they don't apply to. ls_subagent_* is stamped only on the sub-session (subagent) root after its children are created, so it never reaches the subagent's own llm/tool runs.
• Subagent grouping: a subagent sub-session always carries the root session's thread_id, never its own session id, so it groups with the parent thread.
• approval_policy, user_id, user_email, and sandbox_type are omitted — OpenCode's post-hoc session reconstruction exposes no per-run seam for a single approval-policy value, and no stable pseudonymous user/sandbox identifier.
• ls_tool_name is emitted only when a tool run's name differs from the native tool name; OpenCode names tool runs with the native name, so it is normally omitted.
• Existing model-run conventions (ls_provider, ls_model_name, ls_invocation_params, usage_metadata) are preserved unchanged.

Troubleshooting

If traces do not appear in LangSmith:

• Confirm tracing is enabled with TRACE_TO_LANGSMITH=true or "enabled": true in config.
• Confirm an 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 project selected in LangSmith. 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; incomplete turns are not submitted as complete traces.