Trace OpenCode with Litefuse

OpenCode is an open-source terminal coding agent with a client/server architecture, running on Bun. This integration is an OpenCode native plugin installed at ~/.config/opencode/plugin/litefuse.ts — a single TypeScript file with zero npm dependencies. Drop it in the plugin directory and it auto-loads; no opencode.jsonc change needed.

The plugin runs inside the OpenCode server process and subscribes to its event bus and a few dedicated hooks (chat.message, message.part.updated’s step-start/step-finish, tool.execute.before/after, session.idle), producing one Litefuse trace per user turn with real per-event timestamps. Spans are sent as raw OTLP/HTTP JSON via the built-in fetch directly to Litefuse’s OTLP endpoint — no SDK, no node_modules, no build step (OpenCode loads TypeScript directly).

For AI — automatic install

If you’re chatting with OpenCode right now, paste this prompt and the agent will install it end-to-end:

Read https://litefuse.ai/SKILL.md and follow the instructions to install and configure Litefuse for OpenCode.

The skill asks for your Litefuse API keys (and walks you through signup if you don’t have an account), then completes all configuration in place. To configure it manually, read on.

What gets captured

Trace structure

A turn that delegates to a subagent produces a trace shaped like this (real example):

opencode — Turn 1                        (AGENT root — real turn duration)
├── plan (1 tool) #1                     (generation — usage_details + cost, real latency)
├── tool (1 subagent) #2                 (tool — the delegation, from the parent's view)
│   └── subagent                         (AGENT container — the child session)
│       ├── plan (1 tool) #1             (container-local numbering, restarts at #1)
│       ├── tool: read (note.txt) #2
│       └── subagent response            (generation — the subagent's final answer)
└── response                             (generation — final answer, ends the turn)

Design notes:

• Generations are named after what the model did this step, not which model did it (plan (2 tools), response, think) — the model name is the generation’s model attribute, so swapping models doesn’t break dashboards. OpenCode represents one LLM call as a step-start / step-finish part pair; the plugin segments generations from those, taking tokens and cost from step-finish.
• Generation latency excludes tool time. OpenCode emits step-finish after the step’s tools have run, so the plugin ends the generation at the last streamed-content timestamp (≈ when the LLM actually returned), keeping tool-execution time out of the LLM latency — while still taking authoritative tokens/cost from step-finish.
• One step counter per agent container. #N is a single chronological sequence shared by generations and tools. A tool’s agent_plan_step metadata points at the agent_step_index of the generation that requested it — the join is tool.agent_plan_step == generation.agent_step_index. Each subagent container restarts at #1; hierarchy is expressed by the tree.
• Subagent subtrees. OpenCode is a single server process, so one plugin instance sees the events of every session — including the child sessions spawned by the task tool. That means subtrees need no cross-process traceparent protocol: the plugin binds a child session to the parent’s still-running task tool span via the child’s parentID, forming the tool (1 subagent) → subagent container → child-steps three-layer shape. The tool span deliberately wraps the container: tool-span duration − container duration = the real overhead of delegating (child session startup, result collection).
• Each span is sent exactly once, when it ends — OTel spans are immutable; no provisional sends, no upserts. The trace headers (name / session / user / input / tags) ride on every span, so the trace appears in Litefuse as soon as the first observation (usually plan #1, done within seconds) completes — visible mid-turn for long turns.
• Real wall-clock timestamps taken at the moment each event fires — the timeline reflects real LLM latency, tool durations, and the gaps between them.
• Flat agent_* metadata: every OpenCode-specific field is a top-level metadata key with one uniform prefix (agent_step_index, agent_plan_step, agent_duration_ms…) — the same dashboard filter works across every Litefuse agent integration. Sparse: fields with no value simply don’t appear; no null placeholders.
• Fail-open: any unexpected error is written to ~/.config/opencode/litefuse.log and swallowed — the plugin never blocks OpenCode. Unreachable targets are skipped.

Quick start

mkdir -p ~/.config/opencode/plugin
curl -fsSL https://litefuse.ai/integrations/opencode/litefuse.ts \
  -o ~/.config/opencode/plugin/litefuse.ts

cat > ~/.config/opencode/litefuse-targets.json <<'EOF'
[
  {
    "publicKey": "pk-lf-xxx",
    "secretKey": "sk-lf-xxx",
    "baseUrl": "https://litefuse.cloud",
    "environment": "production"
  }
]
EOF
chmod 600 ~/.config/opencode/litefuse-targets.json

OPENCODE_LITEFUSE_DEBUG=true opencode run "Reply with exactly: ok"
tail -3 ~/.config/opencode/litefuse.log
# Expect: "plugin loaded, 1 target(s): https://litefuse.cloud (production)"
#       + "turn complete session=... turn=1 api=1 tools=0"

Environment variables

LITEFUSE_* variables take precedence; the matching LANGFUSE_* variables are accepted as an ecosystem-compatible fallback.

* Only required when not using ~/.config/opencode/litefuse-targets.json. Credentials in the targets file work with no environment variables at all.

Trace metadata reference

Every OpenCode-specific field is a flat top-level metadata key with the agent_ prefix — every Litefuse agent integration shares the same keys, so the same filters and dashboards work everywhere. Litefuse standard fields (sessionId, userId, tags) stay at the trace level via OTel attributes. Sparse: fields with no value never appear, never null.

Trace level:

• agent_turn_number, agent_session_id, agent_cwd, agent_model, agent_provider
• agent_api_calls, agent_tool_calls, agent_steps, agent_duration_ms — turn stats
• agent_image_blocks, agent_prompt_truncated, agent_prompt_orig_len — when applicable

Generation observation:

• agent_step_index — the #N in the name
• agent_provider, agent_stop_reason
• agent_api_duration_ms, agent_time_to_first_token_ms
• agent_tool_call_count, agent_reasoning_tokens, agent_thinking_chars
• agent_input_truncated, agent_output_truncated, agent_output_orig_len — only when truncated

Tool observation:

• agent_tool_name, agent_tool_call_id
• agent_step_index — the tool’s own #N
• agent_plan_step — the agent_step_index of the plan generation that requested this tool
• agent_duration_ms, agent_is_error
• agent_details — OpenCode’s structured tool-result summary (exit code, title, etc.), embedded as an object when ≤ 2 KB; oversized values are dropped wholesale and recorded as agent_details_omitted_len

Subagent container:

• agent_subagent: true, plus the same per-run stats as the trace level (agent_api_calls, agent_tool_calls, agent_steps, agent_duration_ms)

How it works

The plugin subscribes to OpenCode’s event bus and a few dedicated hooks:

Each completed span during a turn is POSTed immediately as OTLP/HTTP JSON, fire-and-forget with a timeout, to <baseUrl>/api/public/otel/v1/traces (Basic auth). Each span is sent once; in-progress steps become visible when they complete.

The root span is delivered synchronously. OpenCode’s headless run exits right after session.idle without awaiting plugin event handlers — at that point the root span (the last span of the turn) would race process teardown and be lost on an async send. So the plugin emits the turn-end root-span batch with one synchronous curl (which blocks the JS thread until delivery completes), guaranteeing it lands; the rest of the turn’s spans still go async and never block. This is why curl is a prerequisite.

For subagents, OpenCode’s task tool spawns a child session. The child’s events flow through the same plugin instance; the plugin binds the child to the parent’s still-running task tool span via the child’s parentID, producing a full subtree. The subagent’s generations carry their own usage, so cost rolls up into the parent trace automatically. One known transient: in the live view a subagent’s steps can appear before their container (the container is sent when the child session ends) — after the turn completes the tree is correct and properly nested.

The plugin is fail-open: any unexpected error only writes to ~/.config/opencode/litefuse.log and returns silently, never blocking or slowing OpenCode.

Troubleshooting

No trace in Litefuse. Check the plugin log:

tail -20 ~/.config/opencode/litefuse.log

An empty log means the plugin didn’t load — confirm the file is at ~/.config/opencode/plugin/litefuse.ts. File present but no plugin loaded line? The plugin found no credentials: check ~/.config/opencode/litefuse-targets.json or the LITEFUSE_* environment variables. A sendSync failed: or send failed: line means a key or network issue: verify the keys and LITEFUSE_BASE_URL.

Root span missing (the trace has children but no AGENT root). Almost always curl isn’t on the PATH — the plugin relies on it to deliver the root span synchronously. The log will show sendSync failed: ... exit=.... Install curl.

A tool failed but isn’t marked ERROR. OpenCode’s bash tool treats a non-zero exit as a successful completion (stderr goes to output, exit code to metadata), not a tool-level error — that matches OpenCode’s semantics. Genuine tool errors (e.g. read of a missing file) are correctly marked level=ERROR.

totalCost is 0. Either a free model (cost really is 0), or your Litefuse project has no pricing entry for the model. Add one under Settings → Models in the Litefuse UI if needed — though OpenCode supplies cost data that the plugin forwards as cost_details, so paid models show cost directly.

Subagents don’t nest (no grandchildren). OpenCode’s child sessions don’t currently get the task tool, so a subagent can’t delegate further — the plugin’s recursive subtree support is ready for when that changes upstream.

Enable debug logging:

OPENCODE_LITEFUSE_DEBUG=true opencode
# Every send / skip / error is written to ~/.config/opencode/litefuse.log

Dual-write to local + cloud: add a second entry to litefuse-targets.json (e.g. a self-hosted instance with "environment": "test"). Unreachable targets are skipped silently and never block OpenCode.

Resources

• OpenCode website
• OpenCode plugins docs
• Litefuse Cloud
• Plugin source: litefuse.ts