Track Claude Code Token Usage & Costs
SuperBased is Claude Code's reference integration. Track Claude Code token usage locally with SuperBased - free, open-source, no telemetry.SuperBased tracks Claude Code token usage and cost on your own machine. SuperBased is Claude Code's reference integration. It captures via hooks in ~/.claude/settings.json, reads the session JSONL under ~/.claude/projects/, and - when you route through the local proxy - records exact provider-reported tokens including 5-minute vs 1-hour cache splits, long-context tier triggers, and reasoning tokens. No account, no telemetry, no data leaves your laptop - SuperBased is a single open-source binary that also covers 39 other AI coding tools.
How SuperBased captures Claude Code
- Where the data lives - SuperBased reads Claude Code's sessions from
~/.claude/projects/<slug>/<session-id>.jsonl(plus hooks in~/.claude/settings.json). - Capture tactic - Hooks fire on every turn as it happens; when you route through the local proxy, SuperBased also records exact provider-reported usage - 5-minute vs 1-hour cache splits, long-context tier triggers, and reasoning tokens.
- Token accuracy: Proxy-exact - Routed through SuperBased's local proxy, Claude Code's token counts are exact - read straight from the provider's response, including cache and reasoning splits where the provider reports them.
- Hooks - SuperBased registers into Claude Code's own hook system, so sessions are captured as they happen.
- MCP - SuperBased can register its MCP server into Claude Code, so you can query your own session history and costs from inside the tool.
2-minute quickstart
Install SuperBased and start the local daemon (it auto-registers hooks for every AI tool it detects):
npm install -g @superbased/observer # or: pip install superbased-observer
observer start
For exact, provider-reported tokens, launch Claude Code routed through the proxy:
observer claude
To wire hooks, MCP, and the proxy route into Claude Code's own config in one step:
observer init --claude-code
Verify capture at any time:
observer doctor claude-code
What you'll see
- Cost breakdown - per-session and per-day spend for Claude Code, priced from SuperBased's built-in model pricing table.
- Session history - every Claude Code session with its model, duration, and token totals, searchable on the local dashboard.
- Cache analytics - prompt-cache read/write splits and cache savings when Claude Code is routed through the proxy.
- Local dashboard - everything is viewable at
http://localhost:8080; nothing is uploaded.
Limitations for Claude Code
- If you route through the proxy, keep the SuperBased daemon running for the whole session - the tool is pointed at it.
- Conversation compression is off by default; token and cost tracking work without it.
FAQ
Is my Claude Code data sent anywhere?
No. SuperBased runs entirely on your machine - it reads Claude Code's local session files (and, if you opt in, proxies your API traffic through localhost). Nothing is uploaded, there is no account, and there is no telemetry.
How accurate are the token counts?
Routed through SuperBased's local proxy, Claude Code's token counts are exact - read straight from the provider's response, including cache and reasoning splits where the provider reports them.
Do I have to change how I run Claude Code?
Only if you want exact proxy counts - then launch with observer claude. Otherwise run observer start once and use Claude Code normally; the watcher captures every session automatically.
Does it track cache and reasoning tokens?
Yes. Routed through the proxy, Claude Code's cache read/write splits and reasoning tokens are captured from the provider's response.
Where does SuperBased read Claude Code data from?
SuperBased reads Claude Code's sessions from ~/.claude/projects/<slug>/<session-id>.jsonl (plus hooks in ~/.claude/settings.json) - all on your own machine. Routing Claude Code through SuperBased's local proxy makes its token counts exact - read straight from the provider's response.