Track what your AI coding tools actually cost — a free, local dashboard (no Docker, no cloud)
AI coding CLIs (Claude Code, Codex, Gemini CLI, and friends) burn tokens fast, and the real consumption is easy to lose track of: flat subscriptions hide it, every tool has its own numbers, and IDE assistants only report to a vendor billing page. This is a small, free, fully-local setup that gives you one private view of what you're spending — by tool, by model, by day, and per project — plus a couple of workflow habits that cut the bill.
Everything here runs on your machine and uploads nothing. No API keys, no cloud account, no Docker. Two small scripts are included in this gist. Examples are Windows/PowerShell; the ideas port directly to macOS/Linux (swap ~/.claude paths and use a shell script).
One mindset shift first: for a subscription (e.g. a flat monthly plan), the dollar figures below are API-equivalent value — what those tokens would cost on metered API pricing — not what you actually pay. It's a consumption meter, not your invoice.
- Instant view: ccusage (zero setup) ccusage reads the local JSONL logs that coding CLIs already write (~/.claude, ~/.codex, ~/.gemini, …) and reports cost + tokens. No install needed — run it with npx:
npx ccusage@latest daily # cost & tokens per day
npx ccusage@latest monthly # per month, broken down by tool & model
npx ccusage@latest session # per coding session
npx ccusage@latest blocks --live # a live, auto-refreshing terminal dashboard
blocks --live alone is a perfectly good "monitor as you go" dashboard — model, burn rate ($/hr), tokens used, and a projection for the current billing block. Pin it in a spare terminal.
- A live status bar (Claude Code) Claude Code can render a status line at the bottom of every turn. Point it at ccusage. In ~/.claude/settings.json:
{
"statusLine": { "type": "command", "command": "ccusage statusline" }
}
You'll get a continuously-updating line like:
Opus 4.x | $X.XX session / $Y.YY today | $Z/hr | ctx 210K (40%)
(Install ccusage globally — npm i -g ccusage — so the status line is snappy.)
- A per-turn cost footer (Claude Code Stop hook) If you want a one-line cost/context summary printed after every assistant turn, add a Stop hook that runs a tiny script. In ~/.claude/settings.json:
{
"hooks": {
"Stop": [
{ "hooks": [ { "type": "command",
"command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"%USERPROFILE%\.claude\scripts\usage-report.ps1\"" } ] }
]
}
}
The script (usage-report.ps1, in this gist) reads the hook's JSON on stdin, aggregates the session transcript (de-duped by message id, priced per model), and emits a {"systemMessage": "..."} line. It's ASCII-only on purpose — PowerShell 5.1 mangles emoji on stdout, which the host would then show as garbage.
- The main build: a global, per-project HTML dashboard usage-dashboard.ps1 (in this gist) produces a single self-contained ~/.claude/usage-dashboard.html you open with a double-click. It combines two data sources:
Cross-tool totals / by-provider / by-model / daily trend — from ccusage (so it covers every CLI ccusage detects: Claude, Codex, Gemini CLI, local models, …).
Per-project breakdown with drill-down — by scanning ~/.claude/projects/ directly (Claude Code is the tool that records per-project transcripts locally). Click a project to expand its by-model, daily, and per-session distribution.
Run it:
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE.claude\scripts\usage-dashboard.ps1" -Open
A few design choices worth copying:
Security: Chart.js is vendored locally (downloaded once next to the HTML) instead of a CDN — no third-party script at view time, works offline, no Subresource-Integrity worries. All dynamic strings are HTML-escaped before going into innerHTML.<br> No keys, no upload: it only reads your own local files.<br> Consistent totals: the per-project estimate uses a simple price table, so its absolute numbers can drift from ccusage's. The script normalizes per-project costs to ccusage's authoritative total — proportions stay accurate and no single project can exceed the grand total. Treat per-project numbers as relative; use ccusage monthly for penny-exact totals.<br> Noise filtered: synthetic / non-billable transcript entries are excluded.</p> <ol> <li>What a local tool can't see (be honest) There are two layers, and only one is local:</li> </ol> <p>Layer Examples Local & free?<br> Consumption (tokens, cost-equiv, model, project, time) CLI tools → local JSONL → ccusage ✅ yes<br> Plan limits & IDE-assistant usage (rate-limit windows, monthly caps, reset dates; VSCode Copilot, IDE-embedded assistants) the vendor's account/billing page ❌ no local source<br> IDE assistants and the plan-limit numbers live in the vendor's account, not a local log — so a local dashboard can only deep-link to those pages (e.g. your GitHub Copilot usage page), not pull the numbers, unless you wire that vendor's API with a token. Anything promising a single cloud pane across all tools wants your logs/keys uploaded — that's the trade-off to weigh.</p> <ol> <li>Bonus: three habits that cut the bill The cheapest token is the one you don't spend twice:</li> </ol> <p>"Done = proven, not written." Don't accept "done" without an evidence artifact — a test run, an HTTP/CLI response, or a screenshot of the app actually working. Most wasted spend is re-doing work that was reported finished but wasn't.<br> Hand off, don't re-research. End a session by jotting Next / open-questions / gotchas into a dated note; start the next one by reading it. Re-discovering yesterday's context is pure token burn.<br> Delegate breadth, right-size effort. Push wide searches to sub-agents that return a conclusion (not a wall of file dumps), and don't run maximum reasoning effort on mechanical edits.<br> Get the scripts<br> This gist includes:</p> <p>usage-dashboard.ps1 — the global per-project dashboard generator.<br> usage-report.ps1 — the per-turn Stop-hook footer.<br> Drop them in ~/.claude/scripts/, wire the two settings.json snippets above, and run the dashboard generator. Windows/PowerShell as written; adapt the ~/.claude paths for macOS/Linux.</p> <p>Disclaimer: provided as-is, no warranty. Model prices change — update the price tables in the scripts. Dollar figures are API-equivalent estimates, not billing statements.</p> <p><a href="https://gist.github.com/Kaidanov/d1b5d63bff857c4ca551a0328f39d6ae">https://gist.github.com/Kaidanov/d1b5d63bff857c4ca551a0328f39d6ae</a></p>
Top comments (0)