Tokscale: A Rust CLI That Reads Local Agent Session Files and Adds Up Your Token Spend
🛰️ Track token usage across AI coding agents from your terminal. 🏅 Global leaderboard with trillions of tokens tracked.
At a glance
- What is it?
- Tokscale scans the on-disk session stores of twelve AI coding agents, normalizes them into a single usage view, and optionally submits an aggregate to a public leaderboard. It is a local-first accounting tool, not a proxy, and its accuracy is bounded by whatever each client happens to write to disk.
- Who is it for?
- Adopt Tokscale if you already run several coding agents on one machine and want one number for the month without wiring up a proxy or a hosted observability service. Do not adopt it if you need per-request attribution for billing, or if your only agent is Cursor and you are unwilling to paste a session cookie into a local cache directory.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Rust, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The accounting gap Tokscale fills between agents
Anyone running more than one coding agent ends up with usage spread across incompatible stores. Claude Code writes under ~/.claude/projects/ and ~/.claude/transcripts/. Codex CLI writes under ~/.codex/sessions/. OpenCode keeps a SQLite database at ~/.local/share/opencode/opencode.db in 1.2 and later, with a legacy JSON message tree at ~/.local/share/opencode/storage/message/ for unmigrated installs. Each client records different fields, and none of them reports the others. Tokscale's job is to read all of those locations and produce one view. The audience is individual developers and small teams who want a monthly figure, not platform engineers building a metering pipeline. The README frames it as a CLI plus a visualization dashboard, and the homepage hosts a 3D contributions graph, so the intended experience includes a browser view on top of the terminal output.
How the scanner maps twelve clients onto one schema
The mechanism is file discovery plus normalization. Tokscale does not intercept API traffic and does not sit between your agent and the model provider; it reads what the client already persisted. Each supported client has a documented location. Amp stores threads under ~/.local/share/amp/threads/. Droid and others follow the same pattern. OpenClaw is the messiest case: the README lists ~/.openclaw/agents/ with per-agent SQLite files matching */agent/openclaw-agent.sqlite plus session JSONL under */sessions/*.jsonl, and it also accepts legacy directory names .clawdbot, .moltbot and .moldbot. That legacy list is a signal about how fast this space renames things, and it is also a maintenance liability, because every rename adds another path the scanner must keep probing. Two clients are handled indirectly rather than through their own store. Sakana Fugu is read through Codex, from ~/.codex/sessions/*.jsonl where the model_provider is sakana. Freebuff shares ~/.config/manicode/ with Codebuff because they run on the same runtime. In the Freebuff case the README is explicit that token usage is estimated from the transcript and that there is no local usage record, which means those figures are derived, not read.
Install and first run: bunx, npm, and the submit subcommand
The README's primary instruction is a single command: bunx tokscale@latest submit. That is the path to the leaderboard and to a public profile, and it is presented as the headline action rather than an optional extra. The package is also published to npm, so a Node or Bun toolchain is the expected environment even though the implementation language is Rust. The Cursor integration is the one that needs setup beyond running a command. Cursor usage is not read from ~/.cursor; the README states plainly that it is not. Instead Tokscale reads a Cursor API export cached at ~/.config/tokscale/cursor-cache/usage*.csv, populated either through desktop auto-login or by pasting a cookie. Environment overrides exist for the clients that need them: COPILOT_OTEL_FILE_EXPORTER_PATH for GitHub Copilot CLI, whose data arrives as OpenTelemetry JSONL under ~/.copilot/otel/*.jsonl, CODEBUFF_DATA_DIR for Codebuff, FREEBUFF_DATA_DIR for Freebuff, HERMES_HOME for Hermes Agent (with ~/.hermes/... as fallback), and GEMINI_CLI_HOME for Gemini CLI (with ~/.gemini/tmp/*/chats/*.json as fallback).
Where the numbers come from, and where they are inferred
Cost reporting is only as good as the token counts underneath it, and those counts arrive by three different routes. The first route is a recorded usage field in a structured log, which is what you get from Codex session JSONL and from Copilot's OpenTelemetry export. The second is a SQLite query against a client database, as with OpenCode 1.2 and OpenClaw's per-agent files. The third is estimation from a transcript, which the README attributes to Freebuff. The distinction matters because an estimated count cannot be reconciled against a provider invoice. There is a second layer of uncertainty on top: any cost figure depends on a price table for each model, and the README does not describe how that table is maintained or how quickly it tracks provider price changes. Treat the cost column as a consistent relative measure across your own agents rather than as a figure you can hand to an accountant. On the Cursor path there is a further constraint: because usage comes from an exported CSV rather than a live local log, the freshness of that cache determines how current the Cursor numbers are.
The Cursor cookie path is the weakest link in the design
Reading a client's local files is a reasonable privacy posture. Requiring a pasted cookie is not the same thing, and the README places that requirement on the Cursor integration specifically. The cache lives at ~/.config/tokscale/cursor-cache/usage*.csv, which is local, but the credential used to fill it is a session token for a hosted service. That is a different trust decision from pointing a scanner at a directory. If Cursor is your only agent, Tokscale asks you to accept an authentication step and a periodic refresh in exchange for a usage view you can already get from Cursor's own dashboard. That is a poor trade. The tool makes more sense when Cursor is one of several clients and the value is the combined total. The other structural limitation is coverage: the README enumerates twelve clients, and any agent not on that list is invisible, with no generic import format described for bringing in a CSV or JSON export of your own.
How Tokscale differs from a metering proxy
The obvious alternative is a gateway or proxy that sits in front of the model API and logs every request, such as LiteLLM's proxy mode or a self-hosted observability stack. The difference in approach is fundamental. A proxy measures what actually crosses the wire, so it captures requests regardless of which client made them and produces counts you can reconcile against a provider. It also requires you to route your traffic through it, which means changing base URLs and accepting a new point of failure in your development loop. Tokscale requires no routing change and no running service; it reads files after the fact. The cost of that convenience is coverage and precision. A proxy sees everything that goes through it and nothing that does not. Tokscale sees exactly the twelve clients it was written for, and it sees only what those clients chose to persist. If your agents run on a remote box or inside a container whose filesystem you do not have locally, Tokscale has nothing to read.
Release cadence, licence, and what that implies for upgrades
The release history shows v4.15.1, v4.15.0 and v4.14.0 landing within roughly a week of each other in late August and early September 2026, on a 4.x line. That cadence is consistent with a project chasing client-side format changes, which is exactly the maintenance burden implied by the legacy OpenClaw directory names and by OpenCode's migration from a JSON message tree to a SQLite database. Expect to upgrade when a client you use changes its storage layout, because a scanner that probes a stale path fails quietly rather than loudly. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, but it governs the code only. The leaderboard submission path sends usage data to a hosted service, and the README does not spell out in the supplied material what is uploaded, how long it is retained, or how a submission is removed. Verify that before running the submit subcommand on a work machine.
Editorial conclusion
Adopt Tokscale if you already run several coding agents on one machine and want one number for the month without wiring up a proxy or a hosted observability service. Do not adopt it if you need per-request attribution for billing, or if your only agent is Cursor and you are unwilling to paste a session cookie into a local cache directory. Before trusting the totals, run the scan once per client and compare a single day's figure against that client's own usage page; the Freebuff path in particular estimates tokens from the transcript rather than reading a recorded usage field, so those numbers are inferred, not measured.
Community notes