# Tokscale: A Rust CLI for Tracking Token Usage Across AI Coding Agents

> Tokscale reads the local session files that Claude Code, Codex CLI, OpenCode, Gemini CLI and other agents leave on disk, then totals tokens and cost in a terminal UI. It is a local-first parser with an optional leaderboard submission, and its accuracy depends entirely on how much each agent writes to disk.

**junhoyeo/tokscale** — 🛰️ Track token usage across AI coding agents from your terminal. 🏅 Global leaderboard with trillions of tokens tracked.

- Repository: https://github.com/junhoyeo/tokscale
- Website: https://tokscale.ai
- Stars: 5,466 · Forks: 440
- Language: Rust
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/junhoyeo-tokscale

## The problem Tokscale solves for people running several coding agents

If you use Claude Code on one project, Codex CLI on another and OpenCode on a third, your token spend is scattered across three provider dashboards with three different reset windows. None of them shows a combined figure, and none of them shows the shape of your usage over time. Tokscale's stated purpose is to monitor and analyze token consumption from a list of coding agents in one place, reading the session data each agent already writes locally rather than calling provider APIs. The intended user is a developer who switches between agents, or a team lead who wants a rough sense of which agent is doing the heavy lifting. The repository also hosts a web leaderboard at tokscale.ai, but the CLI works without it: the README describes submission as an explicit `submit` command, not something the scanner does on its own.

## How the scanner finds your usage: per-client file paths, not an API

Tokscale does not authenticate against Anthropic, OpenAI or Google. It walks known directories on your machine. The README lists a table mapping each client to its data location: Claude Code under `~/.claude/projects/` and `~/.claude/transcripts/`, Codex CLI under `~/.codex/sessions/`, OpenCode under `~/.local/share/opencode/opencode.db` for version 1.2 and later or the legacy `~/.local/share/opencode/storage/message/` tree, Gemini CLI under `$GEMINI_CLI_HOME/tmp/*/chats/*.json` with a fallback to `~/.gemini/tmp/*/chats/*.json`, and others including Amp, Droid, Copilot CLI and Hermes Agent.

That design has a direct consequence. The tool is only as accurate as what each agent persists, and the formats are not stable contracts. The Cargo manifest shows the parsing stack: `simd-json` for JSON, `walkdir` for traversal, `rayon` for parallelism, and `bincode` for a cache. The workspace also depends on `chrono-tz` rather than a fixed offset, and the comment in Cargo.toml explains why: a pinned offset cannot follow daylight saving time, so day-boundary bucketing would drift by an hour twice a year. The CLI pins the machine's IANA zone on first scan via `iana-time-zone`. That is a small detail, but it tells you the author cares about daily totals landing on the right calendar day.

Two entries in the client table are worth reading closely. Cursor is not read from `~/.cursor`; the README says usage comes from a Cursor API export cached at `~/.config/tokscale/cursor-cache/usage*.csv`, obtained through desktop auto-login or a pasted cookie. Freebuff shares `~/.config/manicode/` with Codebuff and, per the README, its token usage is estimated from the transcript because there is no local usage record. Estimated numbers are not the same class of data as parsed records, and the README is honest about which is which.

## Installing Tokscale and running a first scan

The README points at an npm package, and the repository is a Bun workspace with a Rust core, so the published CLI is the intended entry point for most users. Install it globally and run the default command to see the terminal UI:

```bash
npm install -g tokscale
tokscale
```

The scanner reads whatever client directories exist on the machine and prints an overview. If you have never run any of the supported agents, expect an empty view rather than an error.

For a first real use, run a scan before you look at any dashboard, so the cache and the pinned timezone are established:

```bash
tokscale scan
```

According to the README, the timezone used for day bucketing is stored under the `scanner.bucketTimezone` key in the config. If you move between machines or want a fixed reporting zone, set it explicitly rather than relying on the first-scan pin. The README does not document a rollback path for that setting, so treat it as a one-way choice unless you are prepared to clear local state.

Submitting to the public leaderboard is a separate, deliberate step:

```bash
bunx tokscale@latest submit
```

The README presents this as the way to submit usage data and create a public profile. It is the only network-facing command described in the overview, which is a reasonable default: scanning stays local, and publishing is opt-in.

## Where Tokscale gives you the wrong number

The failure mode is structural, not a bug list. Tokscale reconstructs usage from files that other tools own, and those files change. OpenCode's move from a message directory to `opencode.db` is documented in the README as a version boundary, which means anyone on an older or a heavily customized build can fall into the legacy path or out of coverage entirely. Claude Code's `~/.claude/projects/` layout is Anthropic's to change, and nothing in the Tokscale repository can prevent a rename.

The second limitation is cost. Token counts come from the session data; the dollar figure is derived, and the README does not document the pricing table or its update cadence. If you are reconciling a bill, a derived cost is a convenience, not an accounting record. The third is scope: a client absent from the README's table is invisible. If your team standardizes on an agent Tokscale does not list, the combined total silently omits it, which is worse than showing nothing because the number still looks authoritative.

Finally, Cursor coverage depends on a cookie or desktop login to fetch an API export. That is a credential-handling step the scanner does not require for the other clients, and it is the part of the tool most likely to break without warning when Cursor changes its export endpoint.

## Tokscale versus running your own parser or using provider dashboards

The obvious alternative is a short script over the same directories. That is genuinely viable for one agent: a few dozen lines of Python over `~/.claude/projects/` will give you a daily total. What you would be rebuilding is the per-client path table, the legacy-format fallbacks, the timezone-correct day bucketing, the parallel scan and the cache. The Cargo workspace shows that work is split across `tokscale-core` and `tokscale-cli`, with `rayon` and `simd-json` doing the heavy lifting; replicating it for a dozen clients is a maintenance project, not a weekend script.

The other alternative is the provider dashboards themselves. They are authoritative on billing and require no local access, but they are per-provider and they do not read your disk. Tokscale's differentiator is aggregation across agents and a view of usage over time; its weakness is that it is downstream of data it does not control. If you only ever use one agent, the provider dashboard is the better tool and Tokscale adds a parsing layer between you and the source of truth.

## Self-hosting the leaderboard, licence and upgrade cost

The repository ships a `docker-compose.yml` with a Postgres 16 service and an application service built from the included `Dockerfile`. The compose file binds the database to `127.0.0.1:5432` only, and it notes that `postgres:16-alpine` has no TLS configured, so `DATABASE_SSL` defaults to `false` inside the stack while production deployments on a managed database are expected to set it to `require`. The app service reads `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`, which means the hosted leaderboard uses GitHub OAuth. Running this yourself is a real option, but it is a web service with a database, not a CLI feature, and the compose comments warn that the `app` image must be built first with `make docker/build` because `db` is only resolvable inside the compose network.

The project is MIT licensed, which permits commercial use and modification; the repository also accepts sponsorship through GitHub Sponsors. Nothing in the repository indicates a dual licence or a separate enterprise tier, but licence questions about the data you submit to a public leaderboard are a different matter from the code licence, and the README does not describe what happens to submitted usage data.

Upgrade cost is the practical concern. Releases are frequent: v4.14.0, v4.15.0 and v4.15.1 landed within roughly a week of each other in late August and early September 2026, and the workspace version is already 4.16.0. Frequent releases against a dozen changing third-party file formats mean you should expect to update when an agent ships a new session layout, not on your own schedule.

## Conclusion

Adopt Tokscale if you run several coding agents and want one local total instead of five separate billing pages, and if you are comfortable with a tool that parses other projects' private file formats. Do not adopt it if you need per-request audit-grade accounting or if your agents run inside containers where the session directories are not mounted. Before trusting the numbers, run a scan and check the per-client breakdown against one week of provider invoices, because the README documents where each client's data lives but not how closely the derived cost tracks real billing.

## FAQ

### What does "token" mean in Tokscale?

Tokscale reports token counts read from each agent's local session files, so a token here is whatever unit that agent recorded for a request. The README does not define the unit further; the numbers come from the client data rather than from a provider API.

### How can I track AI token usage across several coding agents?

Install the CLI with npm and run the default command, which scans the documented directories for Claude Code, Codex CLI, OpenCode, Gemini CLI and the other supported clients. The README lists the exact data location for each client, and the scan reads only those local paths.

### Does Tokscale read OpenCode token usage from the database or the message directory?

Both, depending on version. The README says OpenCode 1.2 and later uses `~/.local/share/opencode/opencode.db`, including the `opencode-stable.db` channel, while the `~/.local/share/opencode/storage/message/` tree is described as the legacy or unmigrated path.

### Does Tokscale upload my usage data automatically?

No. The README presents submission as the separate `bunx tokscale@latest submit` command, described as the way to submit usage data to the leaderboard and create a public profile. Scanning itself is described as reading local client directories.

### Why does Tokscale use a named timezone instead of a fixed UTC offset?

The comment in the workspace Cargo.toml states that a fixed offset cannot follow daylight saving time, so a pinned offset would drift an hour off local midnight twice a year and split usage near the day boundary. The CLI pins the machine's IANA zone on first scan using `iana-time-zone`.

## Sources

- [junhoyeo/tokscale on GitHub](https://github.com/junhoyeo/tokscale)
- [License: MIT](https://github.com/junhoyeo/tokscale/blob/main/LICENSE)
- [Project website](https://tokscale.ai)
- [README](https://github.com/junhoyeo/tokscale/blob/main/README.md)
- [Releases](https://github.com/junhoyeo/tokscale/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/junhoyeo-tokscale