opencode-telemetry

Local-first historical telemetry for opencode sessions. Track where your tokens go in agent orchestration chains — without external infrastructure.

What it does

• Logs every opencode session to a local SQLite database automatically
• Aggregates costs across orchestration chains (conductor + all child sessions), showing the true total rather than just the parent's share
• Forensic per-session inspection: full token trajectory, turn-by-turn context growth, identified delta drivers ("turn 32 grew by 20k tokens — likely a 41KB bash result entered history")
• CLI binary (octm) generates and saves reports to disk without consuming model tokens to re-emit them
• Zero external dependencies — your data stays on your machine, no collectors required

When to use this plugin

The opencode ecosystem has three telemetry plugins with different scopes. Pick the one that matches your need:

| Need | Plugin | |------|--------| | Inspect a live session interactively to see how tokens are split right now | Opencode-Context-Analysis-Plugin by Igor Warzocha | | Stream telemetry to an existing observability backend (Datadog, Honeycomb, Grafana Cloud) | opencode-plugin-otel by DEVtheOPS | | Analyze sessions historically, forensically, locally, with no infrastructure | opencode-telemetry (this plugin) |

These plugins are complementary, not competing. You can install more than one.

This plugin is built for users who:

• Run complex orchestration chains (e.g. agent swarms with parent/child session dispatch)
• Want to analyze sessions days or weeks after they ran
• Don't have or want an OpenTelemetry collector running
• Need turn-by-turn forensics to understand "where did those tokens actually go?"

We owe a debt of inspiration to both projects above — the live-decomposition approach (Igor) and the streaming-export model (DEVtheOPS). This plugin fills the third corner: persistent, local, forensic.

Installation

npm install -g opencode-telemetry
# or
bun add -g opencode-telemetry

Add to your opencode config (~/.config/opencode/config.json):

{
  "plugins": [
    "opencode-telemetry"
  ]
}

The plugin starts logging automatically. No configuration required.

Quickstart

Pattern 1 — Just install and forget

The plugin starts logging automatically. Nothing to configure. Sessions land in ~/.local/share/opencode-telemetry/data.db.

Pattern 2 — Get a 7-day report

From terminal (no model token cost):

octm report

Or from inside opencode (saves to file, returns the path):

/telemetry-report

Pattern 3 — Forensic inspect of a specific session

octm inspect ses_2073813f

Add --content to fetch and analyze the full prompt content for every turn (requires opencode server running; results are cached locally):

octm inspect ses_2073813f --content

This produces a report with:

• Token trajectory chart across all turns
• Top turn deltas with identified causes
• Agent chain breakdown
• Child session rollup with aggregated costs

Commands reference

octm CLI

octm report [--days N] [--save] [--no-save] [--format md|json]
  Generate a report for the last N days (default: 7).
  Saves to ~/.local/share/opencode-telemetry/reports/ by default.
  --no-save: print to stdout only.
  --format json: output structured JSON.

octm inspect <session_id> [--content] [--save] [--no-save]
  Deep-dive into a session. Supports ID prefix matching.
  --content: fetch and analyze full prompt content (lazy, cached).
  Saves to ~/.local/share/opencode-telemetry/reports/ by default.

octm config show
octm config get <key>
octm config set <key> <value>
octm config reset
  Manage ~/.config/opencode-telemetry/config.json.
  Keys use dot notation: content_cache.enabled, sdk_bridge.enabled, deployment_mode.

octm cache stats
octm cache clear [--older-than <N>d]
octm cache prefetch <session_id>
  Manage the content cache.

octm sql "<query>"
octm sql --file <path>
  Run a read-only SQL query against the telemetry DB.

octm help

Slash commands

| Command | What it does | |---------|-------------| | /telemetry-report | Runs octm report --save, returns the saved file path | | /telemetry-inspect <session_id> | Runs octm inspect --save, returns the saved file path | | /telemetry-db-analyst | Opens a SQL skill for direct DB access |

Slash commands return only the file path — they do not re-emit report contents through the model.

Configuration

Config file: ~/.config/opencode-telemetry/config.json

{
  "version": 1,
  "content_cache": {
    "enabled": true,
    "path": "~/.local/share/opencode-telemetry/content-cache"
  },
  "sdk_bridge": {
    "enabled": true
  },
  "deployment_mode": "auto"
}

| Key | Values | Description | |-----|--------|-------------| | content_cache.enabled | true / false | Whether fetched prompt content is cached to disk | | content_cache.path | path string | Where to store the cache | | sdk_bridge.enabled | true / false | Whether --content fetching is active | | deployment_mode | auto / single_user / server | In server mode, content cache is disabled by default |

Privacy and storage

This plugin stores data locally. Two locations matter:

• Metrics database (~/.local/share/opencode-telemetry/data.db): contains token counts, byte sizes, durations, session metadata. Never contains prompt content.
• Content cache (~/.local/share/opencode-telemetry/content-cache/): populated only when you run octm inspect --content. Caches the prompt content fetched via opencode SDK so re-running analyses is fast.

Disable the content cache persistently:

octm config set content_cache.enabled false

In server-mode opencode deployments, the content cache is disabled by default. No data is sent off your machine. There is no telemetry-of-the-telemetry.

Known limitations

• Subagent attribution requires opencode to populate Session.parentID when spawning child sessions. This is structurally correct in v0.2 but cannot be empirically verified without a live Conductor session. If parent-child costs still show a discrepancy, check docs/v0.2-investigation.md for the diagnostic queries.
• Token composition percentages are byte-based (±15% on absolutes, <5% on ratios). For exact tokenizer counts use Opencode-Context-Analysis-Plugin.
• --content requires opencode server to be running. Without it, only cached content is available.
• Server deployments: content cache disabled by default for privacy.
• No real-time export — for streaming to observability backends, see opencode-plugin-otel.

Contributing

Issues and PRs welcome at github.com/agostinilabsrl/opencode-telemetry.

License

MIT