Obs, the SuperBased mascot: a small robot with a terminal prompt for a face and a cape

SuperBased

Track what every AI coding agent costs. See the limit coming.

See what Claude Code, Codex, Cursor and 37 more AI coding tools cost, per session and per model,
from the tokens your provider actually billed. Free, Apache-2.0, and it runs on your machine.

npm version PyPI version VS Code Marketplace version License: Apache 2.0 Platforms: Linux, macOS, Windows

Quickstart · Docs · Compare · Changelog · Website

Session detail in the SuperBased dashboard: total cost, a low, typical and high cost for the next message, the 5-hour and weekly limit, and the cost of switching to a cheaper model

## Try it in one command ```bash npx @superbased/observer ``` No install, no config, no network. It reads the session logs your coding agents already keep on disk, prints a 30-day cost table by tool and model, and deletes its temporary database on exit. ## Why SuperBased **One local binary that tracks Claude Code token usage, Codex cost and Cursor spend side by side, and helps you control them.** - **Provider-exact cost, not estimates.** An optional local proxy records the tokens your provider returned: net input, 5-minute vs 1-hour cache writes, reasoning tokens and long-context repricing. Log-only trackers have to estimate those. - **Every coding agent in one place.** 40 adapters normalize Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Cline, Aider, Kiro, Devin, OpenCode, Junie and more into one local database. - **Local-first, no account.** No telemetry and no sign-in. The watcher, dashboard, MCP server and CLI make no outbound calls on your behalf; everything lives in one SQLite file under `~/.observer/`. - **Know the next bill before it lands.** Prompt-cache tracking with expiry warnings, a low / typical / high cost band for your next message, and a 5-hour and weekly limit gauge for proxied sessions. - **Guardrails on your own agents.** The guard checks each agent action against built-in rules (destructive commands, secrets egress, MCP pinning, budgets) and your own. It starts in observe mode; `observer guard simulate` replays your history before you turn on enforcement. - **Your agents as terminals, from anywhere.** Launch agent CLIs from the dashboard as real terminals, join a running session from a paired device over your Tailscale tailnet, and hand a session from one tool to another.

Overview page of the SuperBased dashboard: 30-day spend, sessions, actions and proxy-accurate API turns, cache efficiency, cost over time by billing bucket and actions over time by coding tool

## How it compares | | SuperBased | ccusage | CodeBurn | Langfuse | Helicone | LiteLLM | |---|---|---|---|---|---|---| | Built for | Coding-agent cost & control | CC/Codex cost meter | Local CC spend + budget toolkit | LLM-app observability | LLM-app observability + gateway | AI gateway | | Coding tools covered | **40 adapters** | Claude Code, Codex, + companion pkgs | 31-36 per their own docs | Instrument-per-app | Instrument-per-app | Anything routed through it | | Provider-reported (not estimated) tokens | ✓ via local proxy | Partial (from logs) | Partial (from logs) | ✓ (SDK) | ✓ (proxy) | ✓ (proxy) | | Cache 5-min vs 1-hour write split | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | | Reasoning + long-context surcharge accounting | ✓ | Partial | Partial | Partial | Partial | Partial | | Runs 100% local, no cloud required | ✓ | ✓ | ✓ (opt-in team-sync preview) | Self-host a stack | Self-host or SaaS | Self-host | | Agent-queryable memory over your history (MCP) | ✓ | ✓ (usage MCP) | ✓ | ✓ (trace MCP) | ✗ | ✗ | | Cross-tool session handoff | ✓ | ✗ | ✗ | ✗ | ✗ | ✗ | | License | Apache-2.0 | MIT | MIT | MIT (core) | Apache-2.0 | MIT | Checked against each project's public repo (July 2026). Each of these tools is good at what it was built for; the [full comparison](https://superbased.app/docs/compare/overview) covers more tools and when to pick which. ## Install | Channel | Command | |---|---| | npm | `npm install -g @superbased/observer` | | PyPI | `uv tool install superbased-observer` (or `pipx install` / `pip install`) | | VS Code | `code --install-extension superbased.superbased-observer` (Cursor, VSCodium and Windsurf: [Open VSX](https://open-vsx.org/extension/superbased/superbased-observer)) | | Installer | `curl -fsSLO https://github.com/superbasedapp/observer/releases/latest/download/install.sh && sh install.sh` | Every channel ships the same prebuilt, pure-Go binary for Linux (x64, arm64), macOS (Intel, Apple Silicon) and Windows x64. The installer (Windows: `install.ps1`) also offers smaller editions (`minimal`, `developer`, `managed`), checks each archive against `SHA256SUMS` and its Ed25519 signature, never runs sudo, and supports offline installs with `--from-dir`. Run `sh install.sh --help` for every option. ## Get started ```bash observer start # proxy + watcher + dashboard; opens http://localhost:8081 observer scan # backfill history from the session logs already on disk ``` 1. **Route your agent through the proxy** for provider-exact tokens. In the dashboard, open Compression, click your tool's status pill and choose **Route through the observer proxy**: it previews the exact config change and writes only when you confirm. One-off alternatives: `observer claude` / `observer codex`, or `ANTHROPIC_BASE_URL=http://localhost:8820`. 2. **Use your agent as normal.** Sessions, cost and cache numbers appear within minutes. 3. **Optional:** `observer init` also registers the MCP server so your agents can query their own history (it adds tool schemas to every turn, so it stays opt-in). `observer doctor` checks the install; `observer status` shows what has been captured.

Terminals page: Claude Code, Codex, Antigravity CLI and Copilot CLI running side by side as live terminals in one dashboard

## What you get - **Dashboard** (`localhost:8081`): Overview, Live, Sessions, Cost, Plans & limits, Cache, Security, Settings and more, filterable by tool and project, and readable on a phone. - **Cost you can reconcile**: per session, model, project and tool, with cache read/write splits and a session drill-down down to each API turn. - **Cross-tool memory**: an opt-in MCP server so an agent can ask what another agent already read, ran or broke in the same repo, plus `observer --continue-from ` handoffs. - **Waste detection**: stale re-reads, repeated commands and files several agents fight over. - **Terminals**: daemon-owned PTY terminals with multi-seat join, a live cost cockpit and native resume after a restart. - **Your editor and shell**: a VS Code extension (status bar, sidebar, dashboard tab), a one-line `observer statusline`, and a CLI for everything (`observer usage`, `cost`, `predict`, `tail`).
Sessions page: one row per coding-agent session with tool, model, start time, elapsed time, actions and cost, plus tag totals
Sessions: every session from every agent, with cost and tags.		 Cache page: live prompt caches with time left before they expire, cache ratio, reads and writes, and provider coverage
Cache: which prompt caches are warm and when they go cold.
Supported agents include Claude Code, Codex, Cursor, Copilot and Copilot CLI, Gemini CLI, Cline and Cline CLI, Antigravity, OpenCode, OpenClaw, Pi, Hermes, Kilo Code, Qwen Code, Kiro CLI, Kiro Crew, Crush, Kimi Code, Grok, Devin, Aider, Qoder, goose, droid, Open Interpreter, Command Code, Junie, Poolside, Zed, Mistral Code, Muse, Prime Agent, DeepSeek, zcode, Freebuff, Cowork and Grok Bot, plus ChatGPT, Claude, Gemini, Copilot and Perplexity on the web through an optional browser extension. Per-tool setup: [superbased.app/docs/track](https://superbased.app/docs/track/overview). ## Inside a session Click any session to open its detail view. Four of its tabs:
Session detail, Overview tab: total cost, actions, elapsed time and tokens, the action breakdown, token buckets by billing tier and the cost per model
Overview: cost, tokens by billing tier and the models used.		 Session detail, Messages tab: every message in the session with time, role, model, tool calls and cost
Messages: each message with its model, tool calls and cost.
Session detail, Cost and limits tab: low, typical and high cost for the next message and the 5-hour and weekly limit
Cost & limits: what the next message will cost and how much of your limit is left.		 Session detail, Cache tab: the session's live cache and when it expires, cache hits, writes, rewrites and the read to write ratio
Cache: the session's live cache, hits, writes and rewrites.
## Privacy SuperBased sends no telemetry and needs no account. It stores paths, commands and short excerpts, scrubs secrets before anything is written, and binds the proxy and dashboard to `127.0.0.1` by default. The proxy forwards your own requests, unchanged, to the provider you already use. Remove everything with `observer uninstall --all --purge`. Details: [PRIVACY.md](PRIVACY.md). ## Documentation - [Quickstart](https://superbased.app/docs/getting-started/quickstart) and [install options](https://superbased.app/docs/getting-started/install) - [Connect your agents](https://superbased.app/docs/connect/overview) and [track costs by tool](https://superbased.app/docs/track/overview) - Guides: [dashboard](https://superbased.app/docs/guides/dashboard), [token and cost tracking](https://superbased.app/docs/guides/token-cost-tracking), [cache tracking](https://superbased.app/docs/guides/cache-tracking), [cost predictor](https://superbased.app/docs/guides/cost-predictor), [terminals](https://superbased.app/docs/guides/terminals), [security guard](https://superbased.app/docs/guides/security-guard), [MCP server](https://superbased.app/docs/guides/mcp-server) - Reference: [CLI](https://superbased.app/docs/reference/cli), [configuration](https://superbased.app/docs/reference/configuration), [measurement honesty](https://superbased.app/docs/reference/measurement-honesty) ## For organizations Running coding agents across a whole engineering org? SuperBased also offers central visibility across developers, budgets and policy, and SSO sign-in. See [SuperBased for organizations](https://superbased.app/enterprise) or write to contact@superbased.app. ## Community Questions go to [Discussions](https://github.com/superbasedapp/observer/discussions), bugs and adapter requests to [Issues](https://github.com/superbasedapp/observer/issues), and security reports through [SECURITY.md](SECURITY.md). Pull requests are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md) (building needs Go 1.26+, no CGO). If SuperBased saves you a surprise bill, a star helps others find it. ## License [Apache 2.0](LICENSE)