Introduction

SuperBased captures, normalizes, and analyzes the tool-call activity of your AI coding assistants - Claude Code, Codex, Cursor, Copilot, Cline, and a dozen more - and turns it into accurate token counts, cost tracking, and on-demand project knowledge. It is a single Go binary that runs entirely on your machine.

Local-first by default. There is no telemetry, no analytics ping, no required account, and no cloud component in the default install. Everything SuperBased stores lives in one SQLite file at ~/.observer/observer.db.

The three pieces

SuperBased runs three things on localhost, each independently useful:

• Watcher - tails the session-log directories of your AI tools as new events are appended, so your activity is captured with zero configuration.
• Local proxy (127.0.0.1:8820) - an opt-in reverse proxy that sits between an AI client and its LLM provider to capture exact token counts you can't get from the session log alone. It also powers conversation compression.
• Dashboard + MCP server (127.0.0.1:8081) - the web UI where you read your sessions, costs, and trends, plus a Model Context Protocol endpoint your agent can call to query its own history.

What you get

$ observer start
  watcher    ▸ 40 adapters armed
  proxy      ▸ http://127.0.0.1:8820
  dashboard  ▸ http://127.0.0.1:8081

Once it's running, open the dashboard and your sessions start showing up. Token counts, per-model cost, file hot-spots, and a per-message timeline - all from data that never leaves your machine.

Where to next

• Install - npm, pip, the VS Code extension, or a direct binary.
• Quickstart - from zero to a populated dashboard in two commands.
• Core concepts - how the watcher, proxy, and MCP fit together, and what's on by default.
• Connect your AI tool - point your assistant at SuperBased and confirm capture.
• Track costs by tool - per-tool cost & token tracking pages for all 36 supported agents.
• Compare - how SuperBased differs from ccusage, cccost, Langfuse, Helicone, and LiteLLM.
• Glossary - plain-language definitions for tokens, caching, cost attribution, and the rest of the vocabulary.