tokenscope
Open source · CLI + Web + Menu bar
See where your agent's tokens actually go.
Most of what you pay for AI coding, you never see. tokenscope sits in the request path as a transparent proxy, opens up the full request body, and shows you the composition of every dollar — across Claude Code, Aider, Cline, and any agent that speaks HTTP.
| Component | Token % | Cost % |
|---|---|---|
| system prompt | 58.4% | 46.5% |
| tool results | 23.1% | 7.6% |
| model output ← few, but costly | 8.6% | 38.8% |
| tool schema | 7.3% | 5.8% |
| your input | 1.1% | 0.7% |
Token share and cost share tell different stories. You have to read them together.
Three findings from one real session
The bill is mostly the part you can't see.
These aren't estimates from a log summary. They come from decomposing the actual bytes of every request your agent sends.
01
You typed 1% of it.
Your actual request is 1.1% of a call. The other 98.9% is tool definitions, chat history and files read in — sent for you by the framework, re-sent every single turn.
02
Few tokens, most of the bill.
The model's reply is only 8% of the tokens but 39% of the cost — output is priced 5× input, 50× a cache read. Count tokens alone and you'd write it off as noise.
03
One file read. Paid for five times.
A file read is 657 tokens. You paid for 3,300 — because you kept chatting for 5 more turns and it rode along in every one. Real cost = size × resends.
The counter-intuitive part: the cheapest win usually isn't switching to a cheaper model. It's dropping stale files from context and turning on prompt caching. In the sample session, caching alone saved 43%.
Method
Why a proxy, and not log parsing.
Log files record final totals — how many tokens, which model. They don't record what was inside each request. Every agent, though, has to speak HTTP to a model. Put a reverse proxy in the middle and you get the full request body — the only place the composition and the resend amplification actually live.
/ Ollama
Status codes, headers and response bytes pass through unchanged. SSE streams through unbuffered, chunk by chunk. Accounting runs off to the side — if parsing ever fails, your agent keeps working.
- Full request body. The composition split and the resend amplification simply aren't in any log — they only exist in the bytes on the wire.
- One implementation, every framework. Claude Code, Aider, Cline, Kiro CLI, Continue — anything that makes an HTTP call is covered by the same proxy.
- Ground truth, not guesswork. Absolute totals come from the upstream's real usage; the breakdown is scaled to match. Add optional tiktoken for exact tokenization.
How it compares
A log reader shows the sum. tokenscope shows the breakdown.
Menu-bar tools that read Claude Code's JSONL logs are great at one thing: a daily total per model. Here's what sitting in the request path adds.
| Log-parsing dashboards | tokenscopeproxy-based | |
|---|---|---|
| Data source | Final JSONL totals in ~/.claude | Full request body, live in the path |
| Agents supported | Claude Code only | Claude Code, Aider, Cline, Kiro, Continue… any HTTP agent |
| Upstreams | Anthropic cloud | Cloud API or local Ollama — mixed per-agent |
| Token-vs-cost composition | — totals by model | ✓ system / tools / output / schema, token % + cost % |
| Resend amplification | ✗ not present in totals | ✓ size × resends, per tool call |
| Per-task attribution | — by model / day | ✓ by task; sub-agents auto-split into their own sessions |
| Runway & limits | ✗ | ✓ 3-tier: upstream headers → local budget → trend, with live alerts |
| Budget guardrails | ✗ | ✓ warn, or hard-block (429) over budget |
| Surfaces | Menu bar | CLI + web dashboard + menu-bar app |
| Privacy | Local, read-only | Local; offline dashboard, zero external resources |
To be fair: log parsing needs zero setup — if all you want is a daily total for Claude Code, it's the lighter choice. tokenscope asks you to route through a proxy. In return, you see the composition, not just the sum — for every agent you run.
What's in the box
Built to answer two questions: where did it go, and how long will it last.
Many agents, at once
Track Claude Code, Aider, Cline, Kiro CLI, Continue and more side by side. A /a/<name> prefix tags traffic to each agent.
Cloud or local upstream
Point at Anthropic, OpenAI-style gateways, or a local Ollama — and route some agents to the cloud while others stay local.
Runway & live alerts
How much longer can you go? Reads real rate-limit windows when the upstream sends them, falls back to a declared budget, then to trend. Warns before you hit the wall.
Budget guardrails
Set a per-session budget. Get a warning when you cross it, or hard-block over-budget requests with a 429.
CLI, web & menu bar
A terminal status bar, a self-contained web dashboard with deep-linkable sessions, and a macOS menu-bar app — same data, three surfaces.
Fully transparent
Bytes, headers and status codes are untouched; streaming passes through unbuffered. Accounting is side-band and never blocks your agent.
Bilingual, English & 中文
CLI and dashboard share one translation source, so the two never drift. Auto-detects your locale, remembers your choice.
Private by default
Everything stays on 127.0.0.1. The dashboard has no CDN, web fonts or analytics — a 29 KB self-contained HTML that works offline.
Precise where it counts
Absolute totals come from the upstream's real usage. Optional tiktoken upgrades the breakdown from heuristic to exact.
Quickstart
See it in 60 seconds. No API key, no spend.
The demo runs every report on built-in sample data, each table with a plain-language note. Offline, and cleans up after itself.
Prefer no Python? Build a single self-contained binary with bash packaging/build.sh and copy dist/tokenscope anywhere. Other frameworks: run tokenscope env to print their exact connect commands.
Free trial · limited spots
Try tokenscope free on macOS.
The menu-bar app is in free trial right now — macOS only for now, with more platforms on the way. Spots are limited: email us and we'll get you set up.
business_contact@gettokenscope.comClick to copy the address, then email us to start.
macOS (.dmg) · Limited spots — first come, first served.
Read the full guide.
A complete deployment and usage manual — every subcommand, flag and default, checked against the real CLI. In English and 中文.