Local-first token, cost and cache observability for Claude Code.
Requires the observer binary already on your PATH. This plugin is
wiring only — it declares an MCP server and lifecycle hooks that call
observer; it does not download or bundle it.
npm i -g @superbased/observer # or: pipx install superbased-observer
observer start # run the local daemon/plugin marketplace add superbasedapp/plugins
/plugin install superbased@superbased
| Component | What it declares |
|---|---|
.mcp.json |
The observer MCP server: observer serve — on-demand project/session/cost queries from inside Claude Code. |
hooks/hooks.json |
22 lifecycle hooks: ConfigChange, CwdChanged, InstructionsLoaded, Notification, PermissionDenied, PermissionRequest, PostCompact, PostToolBatch, PostToolUse, PostToolUseFailure, PreCompact, PreToolUse, SessionEnd, SessionStart, Setup, Stop, StopFailure, SubagentStart, SubagentStop, UserPromptExpansion, UserPromptSubmit, WorktreeRemove. Each runs observer hook claude-code <event> and records the event locally. |
Captured events are written to the local ~/.observer/observer.db; the hook
commands themselves make no network calls. (Shipping anything off the machine
is a separate, opt-in Teams/org configuration this plugin does not touch.)
observer init --claude-code writes the same hooks into
~/.claude/settings.json and the same MCP server into ~/.claude.json.
Claude Code loads both sources, so carrying both fires every hook event twice
and loads observer's MCP tool schema twice per turn.
With this plugin installed, observer init skips those two steps by
itself and tells you it did. Its proxy-route step still runs, which is what
you want — the plugin does not declare a proxy route, and routing Claude Code
through the local proxy is what makes token counts exact:
observer init --claude-code # writes the proxy route; skips hooks + MCP
observer doctor claude-code # warns if both wirings are somehow presentIf you installed the plugin on an older observer that already wrote the hooks,
run observer uninstall --claude-code to remove init's copy, then
observer init --claude-code to put the proxy route back.
Duplicate fires do NOT duplicate your captured history — the hook rows carry a
deterministic event id and the store upserts on it. They do cost an extra
process spawn per event, a doubled tool schema per turn, and one extra
compaction_events row per /compact (Claude Code's PreCompact payload
carries no identifier for a single compaction, so that one cannot be
deduplicated without risking the loss of a real compaction).
The plugin version is stamped from the observer release tag and kept in
lockstep with the binary — see .claude-plugin/plugin.json.
- Docs: https://superbased.app/
- Source: https://github.com/superbasedapp/observer
- License: Apache-2.0