Local-first token, cost and cache observability for Pi — with nothing to install into Pi.
Every other artifact in this repository is a wiring layer: a manifest or a config block that declares observer's MCP server inside some tool. Pi needs none of them, and this page explains why rather than shipping a package that would do nothing.
Requires the observer binary already on your PATH — that is the
only prerequisite, and it is the same binary every other surface here points
at:
npm i -g @superbased/observer # or: pipx install superbased-observer
observer start # run the local daemonThere is no Pi package to install. Start the observer daemon (above) and use
Pi normally — observer's watcher reads Pi's own session transcripts under
~/.pi/agent/sessions as they are written.
For wire-accurate token counts, launch Pi through observer:
observer pi # or: observer pi --resume <session-id>That writes an observer provider into
~/.pi/agent/models.json — Pi's own documented custom-provider
mechanism, with a baseUrl pointing at the local proxy and an API key
field that names an environment variable rather than storing a secret — and
runs pi --provider observer. Token counts then come from the wire
instead of a self-report. Pi's built-in providers ignore
OPENAI_BASE_URL, which is why the launcher writes a provider instead
of setting an environment variable.
Nothing. That is the point of this page. Three reasons, each checkable:
| Artifact one could ship | Why it is not shipped |
|---|---|
| An MCP server entry | Pi has no MCP client. Its own Philosophy page says: "No MCP. Build CLI tools with READMEs (see Skills), or build an extension that adds MCP support." An MCP entry would have nothing to read it. |
| A Pi extension forwarding lifecycle events to an observer hook | There is no hook to forward to. observer hook accepts claude-code, cursor, codex and hermes; observer hook pi is not a command. An extension calling it would shell out to an error. |
| An extension duplicating capture | Capture is already complete. Observer's Pi adapter reads Pi's full session transcript directly, with no cooperation from Pi required. An extension would re-report what the watcher already has. |
Pi's own answer to "how do I extend this" is build a CLI tool with a
README. Observer is a CLI tool: observer predict,
observer cost, observer sessions and the rest are available
to Pi through its ordinary shell access, no wiring required.
Captured data lands in the local ~/.observer/observer.db.
A Pi extension is a real, documented artifact — a TypeScript module exporting
(pi: ExtensionAPI) => {…}, distributed as a "Pi Package" (a
pi key in package.json) and installed with
pi install npm:<pkg> or pi install git:<url>. The moment
observer grows a Pi hook receiver, that package becomes worth building. Until
then, publishing one would be shipping a shell.
Not possible here: there is nothing to install, so nothing can be installed
twice. observer init writes no Pi config either — the
observer pi launcher writes the provider entry, idempotently, and
only when you use it.
- Docs: https://superbased.app/
- Source: https://github.com/superbasedapp/observer
- License: Apache-2.0