SuperBased

The exact tokens your AI provider billed you — cache splits, reasoning tokens, long-context surcharges — reconciled across 40 coding tools, entirely on your own machine. Nothing you build here ever leaves your machine unless you opt a node into it.

If SuperBased catches something useful in your next bill, a star helps other people looking for the same thing find it.

<p align="center"> <img src="docs/assets/infographics/one-local-path.png" alt="One local path for AI coding activity" width="780"> </p>

Try it in one command

npx @superbased/observer

On a fresh machine — no ~/.observer/observer.db, no ~/.observer/config.toml — this scans every AI coding tool's own local session files into a throwaway temp database, prints one cost table grouped by tool and model, and deletes the database again before it exits. It's local-only: zero network calls, and nothing is written outside that temp directory (foreign-mount adapter mirrors — e.g. WSL reading a Windows-side tool store — are redirected there too; pricing is embedded in the binary, not fetched at runtime).

Already have SuperBased set up (or want the explicit form)? Run observer usage. Bare observer only runs the one-shot on a machine with no local SuperBased state at all — otherwise it prints the usual welcome screen (OBSERVER_ONESHOT=off to always get the welcome screen). This is the zero-config sibling of observer cost: usage rolls up whatever session files it finds into a throwaway DB; cost queries the DB you've actually been capturing into with observer scan / observer start — including any proxy-accurate turns. Full reference: docs/one-shot-usage-report.md.

---

Table of contents

• Try it in one command
• What it is in 30 seconds
• Install
• First-run walkthrough
• Dashboard tour
• Terminals — launch, join, and track your AI CLIs
• MCP server — 25 cross-tool intelligence calls
• Sign in and Cloud Intelligence (beta, experimental)
• Integrations — the stable contract to build against
• API proxy — accurate token capture + compression
• Architecture
• Security & control layer (guard)
• CLI reference
• Configuration
• Post-upgrade hygiene + recovery
• Build from source
• Contributing
• License

---

What it is in 30 seconds

A single local Go binary built on three things a hosted usage console can't give you, in order of how much they matter:

1. Proxy-accurate, cross-vendor cost attribution. An optional API reverse proxy reads the token counts your provider actually billed — net input, 5m/1h cache read/write splits, reasoning tokens, long-context repricing — the same math your invoice uses, not a JSONL-derived estimate. It's accurate enough that it caught its own bug: a Codex reasoning-token double-billing regression SuperBased found and back-corrected months of history for (migration 058, shipped v1.18.0) — the kind of self-audit a vendor console has no incentive to run against itself.
2. Local-first, by construction. The watcher, proxy, dashboard, MCP server, and CLI make zero outbound calls on your behalf — no telemetry, no analytics, no remote reporting. Everything SuperBased captures is written to your own database and stays there. Full details: PRIVACY.md.
3. One capture layer, every tool you actually use. 40 adapters — Claude Code, Codex, Cursor, Cline + Cline CLI, GitHub Copilot + Copilot CLI, Gemini CLI, OpenCode, Google Antigravity, Cowork, Hermes Agent, Kilo Code, Aider, Goose, Devin, Qoder, Crush, Grok, Kiro CLI, Kimi Code, Qwen Code, OpenClaw, Pi, Factory Droid, Open Interpreter, Command Code, and more — parsed into one normalized schema, queryable from a local dashboard, an MCP server (so the tools themselves can query it), and a CLI. (Five more *-web adapters cover ChatGPT/Claude.ai/Gemini/Copilot/Perplexity in the browser — those need the browser-capture extension, which today only installs unpacked; every tool listed above works out of the box.) Twenty-seven of those are also full CLI launchers you can run as real terminals — from the dashboard or your own shell, captured through the same pipeline — see Terminals below.

Raw token counting across tools is table stakes here — it's the substrate the accurate-cost layer above is built on, not the pitch.

One local binary. SuperBased captures, normalizes, and analyzes AI coding tool activity on your own machine: proxy-accurate cost, compression, cache tracking, and session handoff for every AI coding tool you run.

<p align="center"> <img src="docs/assets/screenshots/04-cost.png" alt="Cost tab — proxy-accurate per-model token buckets and dollar cost" width="900"> </p> <p align="center"> <img src="docs/assets/screenshots/11-session-detail.png" alt="Session detail — cost, token buckets, cost predictor and limit gauge" width="900"> </p> <p align="center"> <img src="docs/assets/infographics/intelligence-across-tools.png" alt="Shared local intelligence layer across tools" width="780"> </p>

It answers questions like:

• Where did this week's $147 Claude bill come from — which projects, models, sessions, tool calls? And is that number the same one my provider's invoice would show?
• Did I spend more on Opus or Sonnet? Are my Sonnet sessions hitting the long-context tier and getting repriced at 2×?
• How much did I waste re-reading files that hadn't changed since the last read in the same session?
• Could that trivial Opus session have been done by Sonnet for 1/5 the cost?
• Across Claude Code, Cursor, and Codex working in the same repo, what files are touched by all three? Where are they stepping on each other?
• What will my next message roughly cost — and how much of my 5-hour and weekly subscription limit is left before I hit it?
• Where did my own OpenTelemetry-instrumented agent spend its tokens — with the proxy's exact per-span cost where it routed through the proxy?

---

Install

Pick whichever package manager fits your environment — npm and PyPI ship the same prebuilt binary from the same v* tag, version numbers kept in lock-step.

Via VS Code (Marketplace or Open VSX)

code --install-extension superbased.superbased-observer

The VS Code extension bundles the observer binary, lifts the dashboard / sidebar / status bar / file decorations into the editor, and contributes a terminal profile that pre-exports the proxy env vars so AI CLIs launched from it route through observer automatically. Cursor, VSCodium, and Windsurf install the same VSIX via Open VSX.

After install, VS Code's Get Started page surfaces an in-editor walkthrough; the long-form user guide lives at docs/vscode-extension-user-guide.md and the command + settings reference is at docs/vscode-extension.md.

Via npm (recommended for Node users)

npm install -g @superbased/observer
observer --version

Via pip / uv / pipx (recommended for Python users)

pip install superbased-observer            # plain pip
uv tool install superbased-observer        # uv (isolated env, fastest)
pipx install superbased-observer           # pipx (isolated env)
observer --version

Wheels ship for manylinux2014_{x86_64,aarch64}, macosx_*_{x86_64,arm64}, and win_amd64. uv tool and pipx keep the install isolated from your project's Python env — generally what you want for a CLI tool.

Via go install (latest main, builds locally)

go install github.com/marmutapp/superbased-observer/cmd/observer@latest
observer --version

Via direct download (pre-built per-platform archive)

Each tagged release attaches per-platform archives to the Releases page, verifiable against the published SHA256SUMS:

| Asset | Platform | Contents | |---|---|---| | observer-vX.Y.Z-linux-x64.tar.gz | Linux x86_64 | observer + antigravity-bridge.exe (for WSL2) | | observer-vX.Y.Z-linux-arm64.tar.gz | Linux arm64 | observer + antigravity-bridge.exe (for WSL2) | | observer-vX.Y.Z-darwin-x64.tar.gz | macOS Intel | observer | | observer-vX.Y.Z-darwin-arm64.tar.gz | macOS Apple Silicon | observer | | observer-vX.Y.Z-win32-x64.zip | Windows x86_64 | observer.exe | | SHA256SUMS | — | sha256 of all five archives |

# Linux x64 example — substitute your platform + version.
VERSION=v1.6.21
PLAT=linux-x64
curl -L -O https://github.com/superbasedapp/observer/releases/download/$VERSION/observer-$VERSION-$PLAT.tar.gz
curl -L -O https://github.com/superbasedapp/observer/releases/download/$VERSION/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing
tar -xzf observer-$VERSION-$PLAT.tar.gz
./observer --version

The binary is pure Go — no CGO, no external runtime dependencies. SQLite storage is pure-Go via modernc.org/sqlite. Single static binary; scp it anywhere it runs. Same artifacts ship to npm and to the Releases page (build-once-ship-everywhere CI), so the npm and direct-download paths produce byte-identical binaries.

---

First-run walkthrough

# 1. Start everything: proxy + watcher + dashboard in one foreground
#    process (ctrl-c to stop). Hooks auto-register for every detected
#    AI tool, and the dashboard opens in your browser
#    (http://localhost:8081; suppress with --no-open).
observer start

# 2. (another shell) Backfill from existing session logs so the
#    dashboard has history immediately rather than starting empty.
observer scan

From here the dashboard drives. On an empty database the Overview tab leads with a three-step onboarding checklist — and a demo mode offer if you'd rather look around first: one click seeds a temporary synthetic dataset so every chart renders with realistic data (your real observer.db is never read or written; a persistent banner marks demo state and one click clears it). The two checklist steps that matter:

3. Route your AI tool through the proxy — accurate token counts and conversation compression both need it. On the Compression tab's Proxy banner, click your tool's status pill, then Route through the observer proxy…: the button previews the exact file change (Claude Code: an env.ANTHROPIC_BASE_URL entry in ~/.claude/settings.json; Codex: an observer model provider in ~/.codex/config.toml) and writes only on confirm. Durable — every later session routes automatically. The same section of the Settings → Connected tools panel offers a per-tool setup wizard (hooks / MCP / routing, one consent click per write) and a Launch button. Prefer the terminal? The same routing