opencode Plugin

opencode is a standalone CLI coding agent. Neatlogs hooks into its plugin system: opencode loads the Neatlogs plugin in-process and the plugin records each session as a trace — assistant turns, tool executions, token counts, and cost — then ships it to Neatlogs. No init() call or code changes in your project are required.

The plugin ships spans with a direct, awaited export on each turn (the same model as the Claude Code plugin), so traces land reliably even though opencode run is short-lived.

What gets captured

Each opencode session becomes a trace with this span tree:

Span	What it represents
Agent	`opencode.session` — the session root, with the prompt as input and the final reply as output
LLM	One per assistant turn — model, provider, token counts, cost, and the assistant text (or the tool call it decided to make)
Tool	Each tool execution (read, edit, bash, …) with its input and output

Every span is keyed by the opencode session id as neatlogs.conversation.id, so all turns of a session group together.

Set up (local plugin file)

opencode auto-loads any *.ts under .opencode/plugin/ in your project (or ~/.config/opencode/plugin/ globally). Create a plugin file that re-exports the Neatlogs plugin:

.opencode/plugin/neatlogs.ts

export { NeatlogsOpencodePlugin as default } from 'neatlogs/opencode';

Add a package.json next to your project so opencode can resolve the neatlogs import:

package.json

{
  "type": "module",
  "dependencies": {
    "neatlogs": "^1.0.9"
  }
}

Then run npm install (or pnpm install).

Once neatlogs is installed as an npm dependency you can alternatively register it through opencode.json with { "plugin": ["neatlogs/opencode"] }. Use the neatlogs/opencode subpath — the package root doesn't export the plugin as its default.

Run

Set your project key in the environment, then use opencode as usual:

export NEATLOGS_API_KEY=YOUR_PROJECT_KEY
export NEATLOGS_WORKFLOW_NAME=opencode          # optional grouping label

# one-shot
opencode run -m openrouter/openai/gpt-4o-mini "Read README.md and summarize it"

# or interactive
opencode

Each session shows up in Neatlogs with turn-by-turn LLM spans and tool spans nested under the opencode.session agent root.

Configuration

The plugin reads these environment variables:

Variable	Purpose
`NEATLOGS_API_KEY`	Required — your Neatlogs project key
`NEATLOGS_ENDPOINT`	Backend base URL (default: the hosted cloud)
`NEATLOGS_WORKFLOW_NAME`	Logical grouping label (default: `opencode`)
`NEATLOGS_CAPTURE_SYSTEM_PROMPT`	Set to `true` to capture the system prompt on LLM spans

YOUR_PROJECT_KEY is the same Neatlogs project API key you use for the SDK — opencode sessions land in that project alongside your application traces.

opencode Plugin

What gets captured

Set up (local plugin file)

Run

Configuration

On this page