SuperBased Observer — Command Code

Local-first token, cost and cache observability for Command Code (cmd).

Command Code is one of the few tools here that observer init already wires by itself — this page documents what it writes, and why the second extension surface (Mods) deliberately ships nothing.

Requires the observer binary already on your PATH. This is wiring only — the block below 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

The short version — observer init does it for you. It detects Command Code by the presence of ~/.commandcode/ and writes the entry below into ~/.commandcode/mcp.json (leaving any other server in that file untouched):

observer init

To do it by hand instead — or to add it per project as .commandcode/mcp.json — merge this:

{
  "mcpServers": {
    "observer": {
      "command": "observer",
      "args": [
        "serve"
      ]
    }
  }
}

What it wires

Key	Value
command + args	observer serve — resolved from PATH.

This block is not hand-typed: it is the entry observer's own MCP registrar writes, read back out of a throwaway sandbox home. The one difference from what observer init puts on your machine is the binary path — init writes the absolute path of the binary that ran it, and a published listing has to resolve observer from PATH instead.

The observer server exposes observer's project, session, cost and cache queries as tools, reading the local ~/.observer/observer.db. It makes no network calls of its own. Command Code capture is unaffected either way: observer's watcher reads its JSONL sessions under ~/.commandcode/projects regardless.

Why there is no Mod

Command Code's other extension surface is Mods — single-file TypeScript modules declared by a commandcode key in a package.json and installed with cmd mods add. It is a real, first-party API (Command Code builds its own providers on it), and observer ships no Mod for it, for one reason: there is nothing to put inside.

• A Mod's job would be to declare the MCP server — which the config file above already does, through a registrar observer actually owns.
• The other half of the ModApi is lifecycle hooks (beforeToolCall, transformInput, onStop). Observer has no Command Code hook receiver: observer hook accepts claude-code, cursor, codex and hermes. A Mod's handlers would have nothing to call.

So a Mod would be a package whose only content is a second spelling of an entry that already exists. If observer grows a Command Code hook receiver, that changes, and the Mod becomes worth publishing.

Double-wiring

observer init writes this exact server into ~/.commandcode/mcp.json. If you also paste the block above into the project-scoped .commandcode/mcp.json, Command Code loads the same tool schema twice — harmless to your data, wasteful of context. Keep one.

The automatic detect-and-skip observer init performs for the Claude Code plugin is claude-code-only (internal/claudeplugin); no equivalent probe exists here. Documented, not built.

Links

• Docs: https://superbased.app/
• Source: https://github.com/superbasedapp/observer
• License: Apache-2.0