Skip to content

README.md

Latest commit

 

History

History
110 lines (84 loc) · 3.73 KB

README.md

File metadata and controls

110 lines (84 loc) · 3.73 KB
Raw

@superbased/opencode-plugin — OpenCode plugin

Local-first token, cost and cache observability for OpenCode. The plugin registers observer's MCP server through OpenCode's config hook, so you never edit opencode.json's mcp block by hand.

Requires the observer binary already on your PATH. This package is wiring only — it declares an MCP server that runs observer; it does not download or bundle it.

npm i -g @superbased/observer     # or: pipx install superbased-observer
observer start                    # run the local daemon

Install

Add the package to the plugin array of your opencode.json (~/.config/opencode/opencode.json for every project, or a project-local opencode.json):

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

OpenCode installs npm plugins with Bun at startup and caches them in ~/.cache/opencode/node_modules/ — there is no separate npm install step.

Not published yet. @superbased/opencode-plugin is not on npm; this directory is the package source. Publishing is an operator-gated step.

What it wires

The plugin's config hook adds one entry to OpenCode's MCP map:

{
  "mcp": {
    "observer": {
      "type": "local",
      "command": ["observer", "serve"],
      "enabled": true
    }
  }
}

That is byte-for-byte the entry observer init --opencode writes — it is generated from the same registrar (src/wiring.generated.ts), not re-typed. observer serve speaks stdio MCP and exposes observer's project, session, cost and cache queries as tools (reads of the local database; continue_session writes a handover file only when you pass write_file=true).

No lifecycle hooks are registered. OpenCode's tool.execute.before/after and event hooks could surface cost hints in-session, but observer's capture does not need them: the watcher already reads OpenCode's own session store, and observer opencode routes turns through the local proxy for exact token counts.

Double-wiring: handled, in the one case we can

The hook skips itself when the server is already configured:

if (config.mcp[OBSERVER_MCP_SERVER_NAME]) return;

So carrying both this plugin and observer init --opencode's write is safe — whichever entry is already in the merged config wins, and the server is declared exactly once. Note this is a same-key check inside OpenCode's own config object, not a probe of what observer wrote; if you registered the server under a DIFFERENT name, both load.

(The on-disk detect-and-skip that makes observer init stand down for the Claude Code plugin is internal/claudeplugin — claude-code-only. There is no OpenCode equivalent, and none was built this round; observer init --opencode still writes its entry. The config-hook guard above is what makes that harmless.)

Package layout

Path Owner
src/wiring.generated.ts Generated by plugins/plugingen from the real MCP registrar. Never edit.
README.md Generated (this file).
src/index.ts Hand-written SDK glue: the config hook.
package.json, tsconfig.json Hand-written. The version is stamped by scripts/sync-npm-version.sh in lockstep with the observer release.

Build (operator step, before a publish):

npm install && npm run build      # tsc → dist/

dist/ is not committed. @opencode-ai/plugin is a devDependency and a type-only import, so the built plugin has no runtime dependencies.

Links