OpenCode Observability

---

OpenCode Observability turns the session history OpenCode already writes to disk into a fast, local dashboard. It runs a single monitor server on your machine, reads OpenCode's session store read-only, and streams live activity into a browser UI. Nothing is sent to the cloud — there is no account, no external endpoint, and no data ever leaves localhost.

OpenCode is the focus. The live monitor and dashboard are built around OpenCode. Because the session viewer happens to be harness-agnostic, Claude Code and Codex sessions can be browsed in the same UI too — a bonus, not the main event.

npx opencode-observability
# → open http://127.0.0.1:3737

✨ Features

• 🛰️ Live Monitor — every open OpenCode session as a card with an inline real-time timeline (last 5 minutes), so you can spot a stuck agent, a retry storm, or an error the moment it happens.
• 📊 Dashboard — token consumption, model performance, MCP usage, error patterns, subagent trends, and an activity heatmap across your OpenCode sessions.
• 🔍 Session Viewer — replay any past conversation with full Markdown rendering, Shiki syntax highlighting (17 languages), and live Mermaid diagrams.
• 🔌 Zero-setup plugin — the OpenCode plugin streams live events and auto-starts the monitor, so there's no server to babysit.
• 🔒 Local by design — read-only access to your existing session store, a metadata-only live boundary, and no raw payloads exposed to the browser.
• ➕ Bonus — Claude Code & Codex — the same viewer also opens Claude Code and Codex sessions, each with a /monitor command handled by a hook before the model runs (zero token cost).

🚀 Quick Start

Requires Node.js ≥ 22.

# Run the monitor with no install
npx opencode-observability

# …or install globally
npm install -g opencode-observability
opencode-observability

The server starts at http://127.0.0.1:3737 and opens on the live Monitor. It immediately reads whatever OpenCode history already exists on your machine — no configuration required.

🧩 Integrations

OpenCode

Add the plugin to your OpenCode config (opencode.json or ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-observability"]
}

The plugin streams live session events and heartbeats to the monitor. If the monitor isn't running yet and the ingest target is local, the plugin auto-starts a single shared server with a lock — so multiple OpenCode processes share one monitor instead of spawning duplicates.

Bonus: Claude Code & Codex

OpenCode is the focus, but since the viewer is harness-agnostic this repo also ships marketplace plugins that add a monitor command to Claude Code (/oc:monitor) and Codex (@monitor), opening the current session in the viewer. Each hook runs before the model, so it costs zero tokens.

Claude Code

/plugin marketplace add abekdwight/opencode-observability
/plugin install oc@opencode-observability

Codex

codex plugin marketplace add abekdwight/opencode-observability
codex plugin add opencode-observability@opencode-observability

Run /oc:monitor in Claude Code (Codex uses /monitor or the @monitor skill). Plugin hooks need a one-time trust approval on first use. Starting with plugin version 0.3.1, the installed hook is only a thin launcher; it delegates monitor behavior to npx --yes opencode-observability@latest hook <codex|claude>, so future hook behavior ships through the npm package. If the local viewer server is not running, the npm CLI starts one in the background with npx --yes opencode-observability@latest.

Existing plugin installs from before 0.3.1 need one manual update so the thin launcher is installed: