SuperBased Observer CLI
A local binary tracks Claude Code, Codex and Cursor spend from provider-billed tokens and enforces guardrails on your agents.
- 59 ★ on the repository
- Last commit
Extended access
Why this level
- The tool reads session logs with paths and commands, and the optional proxy sits between agent and provider and sees requests
Install
- Works in
Manual install
npx @superbased/observerA one-off report with no install, and the temporary database is deleted on exit. Permanent install: `npm install -g @superbased/observer`.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The tool reads session logs with paths and commands, and the optional proxy sits between agent and provider and sees requests
This is third-party code. Review the repository files before installing.
What it does
Observer reads the session logs that agents already keep on disk and merges them into one local SQLite database. The `npx @superbased/observer` command with no install prints a 30-day spend table by tool and model and deletes its temporary database. Adapters cover Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Cline, Aider, Kiro, Devin, OpenCode and more. An optional local proxy records the tokens the provider returned: net input, 5-minute and 1-hour cache writes and reasoning tokens. That gives exact sums instead of estimates from logs. The dashboard shows cache expiry, a cost range for the next message and limit gauges. Guardrails check agent actions: destructive commands, secret egress, MCP pinning and budgets. They start in observe mode, and `observer guard simulate` replays history before enforcement is turned on.
Who it is for. Developers and teams spending noticeable money on agent subscriptions and APIs who want spend by tool and model.
Good fit when
- An unexpectedly large number of tokens went in a month and you need to see which agent and model ate the budget
- A spend check with no install is needed, one command reading logs already on disk
- Before turning on bans you want to replay history and see what the rules would have blocked
- A prompt cache is expiring and you need to know when the next message gets more expensive
Not a fit when
- Monitoring of an LLM-based application is needed, since the tool watches coding agents, not your product
- A cloud service with a team account is needed and a local database is not enough
- Policy forbids a local proxy between agent and provider
Example request
Show 30-day spend by agent and model and say which guardrails would have fired in my history.Limitations
macOS 13 Ventura or newer is required, and for macOS 12 the README advises staying on v1.36.0. Only the proxy gives exact tokens, while logs give approximate costs. Session content is not uploaded without explicit consent, but the database stores paths, commands and short excerpts on disk, and secrets are scrubbed before writing. The proxy and dashboard listen on `127.0.0.1`. Guardrails start in observe mode. Running agents in dashboard terminals and joining from another device over Tailscale are enabled separately. GitHub metadata shows no detected license while the README states Apache-2.0.
How to disable. Run `observer uninstall --all --purge` to remove connections and local data. If you routed an agent through the proxy, restore its original address in its settings.
FAQ
What does the no-install command do?
`npx @superbased/observer` reads agent logs on disk, prints a 30-day spend table by tool and model and deletes the temporary database.
Why is the proxy more exact than logs?
The proxy records the tokens the provider returned, including cache writes and reasoning tokens. From logs they have to be estimated.
How do I route an agent through the proxy?
In the dashboard open Compression, click the tool status and choose to route through the observer proxy. The proxy forwards your requests to the provider unchanged.
Where do guardrails apply?
They check agent actions against built-in and your own rules. Observe mode is the default, and `observer guard simulate` shows what would have been blocked.
Is there VS Code integration?
Yes, the `superbased.superbased-observer` extension adds a status bar, a sidebar and a dashboard tab. For Cursor and Windsurf it is on Open VSX.
Discussion
No questions or reviews yet.
Related
CLI toolsClawMetry reads the session files agents already write and shows the timeline, tool calls, tokens and cost in one dashboard.
A local dashboard for Claude Code: a live graph of sessions and subagents, tokens, cost and file conflicts.
Local ledger of AI agent work: tokens, estimated cost, steps, changed files and checks per task for Claude Code, Codex and OpenCode
A local real-time dashboard for Claude Code and Codex sessions: agent activity and tool calls
A terminal dashboard for spend, quotas and rate limits across Claude Code, Codex, Cursor, Copilot and other AI tools
Reading, fixes, tests and reviews go to parallel workers on cheap models; the main agent gets a short answer, a diff, a receipt
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| SuperBased Observer (this card) | no | 59 | ||
| ccusage | no | 19,425 | counts spend from Claude Code and Codex logs; Observer adds a proxy with exact tokens and guardrails | |
| CodeBurn | yes | not required | 11,782 | local spend tracking and budgets; Observer covers 50 adapters and checks agent actions |
README in short
Everything lives in one SQLite file under `~/.observer/` with no account. Costs are read from logs by default, and the proxy is enabled separately for exact figures.