Tokscale: AI Token Usage Tracking CLI

What is Tokscale?

Tokscale is a command-line tool and terminal UI, written in Rust, that reads local session data from AI coding agents like Claude Code, Codex CLI, OpenCode, and Cursor IDE to report the tokens you've used and what they cost. It rolls everything into one contribution-graph-style dashboard instead of making you check each agent's own usage screen on its own.

Core Features for AI Token Management

• ✓Reads local session data from 20+ coding agent CLIs and IDEs — Claude Code, Codex CLI, OpenCode, Cursor IDE, Gemini CLI, Amp, Droid, Cline, Goose, Devin CLI, and more — per the README's client table, instead of requiring a separate API integration with each one.
• ✓Interactive TUI built on Ratatui with views for Overview, Models, Daily, Hourly, Stats, and Agents, plus an opt-in Minutely view, keyboard and mouse navigation, and 12 selectable color themes.
• ✓Real-time pricing pulled from LiteLLM's pricing data with a 1-hour on-disk cache, an automatic OpenRouter fallback, and separate Cursor model pricing for newly released models.
• ✓A native Rust core handles parsing and aggregation, which the README says makes processing roughly 10x faster through parallel file scanning and SIMD JSON parsing.
• ✓Six group-by strategies — model, client+model, client+provider+model, workspace+model, session+model, and client+session+model — including a `sessionId` field for attributing cost back to one agent-CLI session.
• ✓A GitHub-style contribution graph with 2D and 3D web visualization, exportable via `tokscale graph --output data.json`.
• ✓Reports attributed to tasks offer the ability to summarize sessions and group tasks, powered by an LLM. They also feature multi-backend support for Apple FM, Claude, Codex, Gemini, or Kiro.
• ✓A social leaderboard — running `bunx tokscale@latest submit` submits your usage data and creates a public profile you can compare against others.

Getting Started with Tokscale

Tokscale ships as `tokscale`, an npm alias package (the README compares it to how the `swc` package works) that installs `@tokscale/cli`, including the compiled native Rust core `@tokscale/core`. Run `npx tokscale@latest`, `bunx tokscale@latest`, or `deno x npm:tokscale@latest` and you get the full interactive TUI immediately — no separate install step. Add `--light` for table-only output instead of the TUI. You need Node.js or Bun installed; a Rust toolchain is only needed if you want to build the native module from source. To build from source: clone the repo, install Bun, run `bun install`, then `bun run build:core` to compile the native module (required for the CLI to function — it does the actual file parsing and aggregation) and `bun run cli` to run it locally. The README says prebuilt binaries ship with the published package, so this source path is only needed for local development.

Navigating the Tokscale TUI and CLI

The default `tokscale` command launches the TUI; `tokscale models`, `tokscale monthly`, and `tokscale hourly` open specific tabs directly, and `tokscale tui` opens it explicitly. `tokscale --light` prints the legacy table output instead. Inside the TUI, arrow keys or Tab switch views, `g` opens a group-by picker (model, client+model, client+provider+model, workspace+model, session+model, or client+session+model), `s` opens a source/client picker, `p` cycles through the 12 color themes, `y` copies the selected row, and `e` exports to JSON. Scope any report to specific agents with `--client`/`-c` (comma-separated or repeatable, e.g. `--client opencode,claude`), and to a date range with `--today`, `--week`, `--month`, `--since`/`--until`, or `--year`. `tokscale graph --output data.json` and `tokscale models --json` push data out for other tools to use. One thing to note: version 4.0.0 removed the old per-client boolean flags (`--opencode`, `--claude`, etc.) — those now error, so `--client` is the only supported way to filter by agent.

Other AI Token Tracking Tools

Common Questions About Tokscale

The problem it solves

Developers who use more than one AI coding agent — say Claude Code for some projects, Codex CLI or Cursor for others — have no single place to see combined token spend. Each agent tracks and reports its own usage in its own format and location, spread across dozens of different paths (`~/.claude/projects/`, `~/.codex/sessions/`, Cursor's own API cache, and so on). Tokscale's README addresses this head-on by shipping a local reader for each agent's own session-storage format, instead of asking developers to reconcile the numbers by hand across tools.

Best use cases

• •A developer juggling more than one AI coding agent (say Claude Code plus Codex CLI and Cursor) who wants one place to see combined token spend instead of checking each tool's own usage screen.
• •Attributing LLM cost per session in a multi-agent runner or IDE, using `--group-by session,model` or `client,session,model` to join cost data back to a specific `session_id`.
• •Exporting usage data as JSON (`tokscale --json`, `tokscale graph --output data.json`) to feed an internal dashboard or spreadsheet.
• •Filtering spend by date range or client to build a monthly or per-project token/cost report (`--since`/`--until`, `--client`, `--week`/`--month`).
• •Competing on Tokscale's global leaderboard by submitting usage data and getting a public profile via `bunx tokscale@latest submit`.

Who should try it — and who should skip

Try Tokscale if you regularly switch between more than one AI coding agent — Claude Code one day, Codex CLI or Cursor the next — and want a single terminal dashboard for combined token spend instead of piecing together separate usage screens. It also fits if you like living in a TUI and want cost broken out by session for a multi-agent workflow. Skip it if you use exactly one coding agent that already surfaces its own usage clearly, or if you're not comfortable running a tool that reads local session files across `~/.claude`, `~/.codex`, `~/.cursor`, and dozens of similar paths to build its report.

Related repositories