Fast usage reports for Claude Code, Codex, and 17 more coding agents. See token counts and estimated cost, follow sessions live, or export JSON for your app. A native Rust CLI that reads the logs already on your machine. Local reports need no account or API key.
Install · Migrate from ccusage · Reports · Live dashboard · Benchmarks · Docs
Choose your platform. Native downloads are available for Apple Silicon / ARM64 and Intel / AMD x64.
Release status: Native downloads and Homebrew install v1.1.6. npm currently installs v1.1.2 while its package update awaits publication. Use the native Windows ZIP for the latest fixes.
With Homebrew installed:
brew install maxmoneycash/tap/turbotokensFor a standalone install, follow the macOS instructions. No Node.js runtime is needed.
For v1.1.6, download the Windows x64 ZIP or Windows ARM64 ZIP. Extract it, open PowerShell in that folder, and run:
.\turbotokens.exe doctor
.\turbotokens.exe claude daily --last 7The Windows guide explains checksums, PATH, and WSL. No Node.js runtime is needed.
With Node.js installed, npm currently provides v1.1.2. Run this in PowerShell or Command Prompt:
npm install -g turbotokens
turbotokens --versionRun in your terminal:
curl -fsSL https://raw.githubusercontent.com/seammoney/turbotokens/main/install.sh | shThe installer selects x64 or ARM64 and prints the install location. If it uses ~/.local/bin, add that directory to your PATH:
export PATH="$HOME/.local/bin:$PATH"The v1.1.6 Linux downloads are static builds tested on Ubuntu 22.04, Debian 12, and Alpine 3.22. See Linux instructions for distro compatibility, persistent PATH setup, and pinned releases. No Node.js runtime is needed.
These commands work on all three platforms after installation:
turbotokens --version
turbotokens doctor
turbotokens
turbotokens claude daily --last 7
turbotokens codex daily
doctor finds your agents' logs. Plain turbotokens shows daily usage across
agents; name claude or codex to focus on one source.
You can also try npx turbotokens on any platform with Node.js. The npm package downloads and launches the native executable; keep npm installation scripts enabled. All install and upgrade options →
Install alongside it, choose the same agent, and compare the fields your app reads:
# Claude-only JSON, suitable for a Claude usage integration
turbotokens claude daily --offline --json
# Codex-only JSON
turbotokens codex daily --offline --jsonUse an explicit agent when replacing a single-source report. Plain turbotokens daily combines detected agents and has a different JSON shape. The npm package exposes a CLI; it does not replace older ccusage JavaScript imports.
The migration guide includes command mappings, a Node.js subprocess example, rollback advice, and an executable compatibility check. Seventeen recorded cases compare released native binaries on synthetic Claude histories, including token categories, filters, duplicates, and cached versus uncached JSON.
| Find out | Run |
|---|---|
| Usage by model | turbotokens claude daily --breakdown |
| Which Claude project accounts for the spend | turbotokens claude daily --instances |
| Usage by session | turbotokens codex session |
| Monthly trends | turbotokens monthly --since 20260101 |
| Current Claude billing block | turbotokens blocks --active |
| Each agent's share, as JSON | turbotokens daily --json --by-agent |
Filter by date, project, or timezone where the source supports it. Run turbotokens <agent> <command> --help for that report's options.
All 19 supported agents
Claude Code · claude |
Codex · codex |
OpenCode · opencode |
Amp · amp |
Gemini CLI · gemini |
GitHub Copilot · copilot |
Kimi · kimi |
Grok Build · grok |
Qwen · qwen |
Droid · droid |
Codebuff · codebuff |
Hermes · hermes |
Goose · goose |
Kilo · kilo |
OpenClaw · openclaw |
pi-agent · pi |
Antigravity · antigravity |
ZCode · zcode |
Muse · muse |
Agent formats differ. Available model, project, cache, and session details depend on what each agent records. Live mode currently supports Claude Code, Codex, and Grok Build. Adapter notes →
Grok live mode and stream require v1.1.3 or newer. Check the release status before installing.
turbotokens live # Claude Code
turbotokens live --agent codex
turbotokens live --agent grok
Live mode polls every 100 ms by default. It shows new usage as the agent writes its logs. Static preview · Recording source
For scripts and monitoring:
turbotokens stream --offline # NDJSON snapshot and usage events
turbotokens live --alert-cost 25 # Notify at $25 estimated spend
turbotokens live --serve 127.0.0.1:9090 # Local Prometheus endpointBudget alerts can call a webhook; they do not stop the coding agent. See live options and payloads, or add turbotokens statusline to your Claude Code status line.
turbotokens wrapped --year 2026 --svg wrapped.svg
Export your yearly summary as an SVG for a README, a personal site, or the show-and-tell thread. Check project names before sharing your own card.
Prefer a contribution heatmap?
turbotokens heatmap --svg heatmap.svg
Add --cost to color by estimated spend, or omit --svg for a terminal view. Both heatmap and wrapped support JSON export.
All product images use synthetic data. The SVG previews are direct CLI exports.
A cached Claude daily report took 12.9 ms on 3.63 GB of logs, versus 3.65 s for ccusage. This is a measured repeat-report workload, with no daemon running.
Measured September 6, 2026, on an Apple M1 Max with native ARM64 releases: turbotokens 1.1.0 and ccusage 20.0.20. Five interleaved runs per size; median wall time includes JSON output. Pricing and caches were primed, and all four token categories matched on each run. This measures recorded usage counters, not text tokenization.
The cache is Claude-specific. First scans, changed files, other agents, and different machines take different paths. With 1,000 smaller files (72 MB total), the measured daily medians were 12.7 ms and 71.9 ms.
Commands, raw samples, versions, and binary hashes →
Monthly reports and the first scan
| Transcript size | turbotokens 1.1.0 | ccusage 20.0.20 | tokscale 4.15.1 |
|---|---|---|---|
| 72 MB | 38 ms | 71 ms | 107 ms |
| 362 MB | 147 ms | 273 ms | 340 ms |
| 725 MB | 263 ms | 539 ms | 751 ms |
| 1.81 GB | 622 ms | 1,230 ms | 1,859 ms |
| 3.63 GB | 1.54 s | 4.83 s | 3.99 s |
Measured September 6, 2026, on an Apple M1 Max. Five runs per tool and size, interleaved; median process wall time includes JSON output. Each dataset contains six synthetic files. The largest contains usage counters totaling 50 billion tokens; it is 3.63 GB of transcript data, not 50 billion tokens of text being tokenized. Monthly reporting uses a different aggregation path from the cached daily fast path.
Different file counts, agent formats, machines, and background load can change the result. Costs can differ with pricing sources, so the cross-tool check compares token categories, not estimated dollars. Tokscale has no equivalent daily report command; it is included in the matching monthly comparison.
Raw samples, binary hashes, and reproduction commands →
What about the first scan?
In a separate cache-on/cache-off test, turbotokens scanned the 3.63 GB history in 1.10 s with its parse cache disabled, then returned the cached daily report in 9 ms. Both used a warmed OS file cache and offline pricing. Every cached and uncached JSON result was byte-identical.
See the cache benchmark for the separate run and its raw samples.
- Your logs stay local. Reports aggregate usage records already on your machine. They need no transcript upload or turbotokens account.
- Costs are estimates. Model prices and recorded usage can differ from a provider bill or subscription allowance. Missing local logs cannot be reconstructed.
- Network access depends on the feature. Use
--offlinewhere supported for embedded or cached pricing. Installation, refreshed pricing, subscriptionlimits, and configured webhooks contact their respective services.
An empty or surprising report starts with turbotokens doctor. Check the source, date range, timezone, and adapter's log locations. For a counting issue, share a small sanitized fixture in a bug report.
| Guide | What it covers |
|---|---|
| Install and upgrade | macOS, Windows, Linux, checksums, PATH, and pinned releases |
| Migrate from ccusage | Commands, JSON contracts, subprocesses, and reproducible checks |
| Usage guide | Filters, live events, alerts, status line, completion, and the optional daemon |
| Adapter notes | Supported records and source-specific behavior |
| Contributing | Build, test, and report a reproducible bug |
Build from source
git clone https://github.com/seammoney/turbotokens.git
cd turbotokens/rust
cargo build --release --bin turbotokens --features fetch-litellm-pricing
cargo test --workspace --features fetch-litellm-pricing
cargo clippy --release --bin turbotokens --features fetch-litellm-pricingThe repository pins its Rust toolchain. Builds embed a pricing snapshot; set TURBOTOKENS_PRICING_JSON_PATH to use a local LiteLLM pricing file. Parsing and cache changes must preserve report JSON, with fixtures and measured performance checks.
If turbotokens is useful to you, a star helps other developers find it. Contributions with real workloads and reproducible counting bugs are welcome.
MIT. turbotokens began as a fork of ccusage by @ryoppippi. The original copyright is preserved alongside the rewrite's attribution. Thanks to the ccusage contributors and the projects whose local usage formats make these reports possible.