AI Token Spend

Personal AI‑spend intelligence for developers. One command, zero setup, 100% local.

AI Token Spend reads your Claude Code and GitHub Copilot session files directly from disk and opens a local browser dashboard that shows where your AI spend actually goes — in real US dollars and GitHub AI Credits, broken down by tool, model, project, activity and tool‑call. It flags waste, compares models, tracks how much value you’re getting from your plan, and teaches token‑saving best practices. Nothing is transmitted anywhere: no API calls, no telemetry, no accounts.

v2.0.0 is a complete overhaul — sidebar navigation, a real USD cost engine, the new GitHub AI Credits billing model, and a full analytics suite (per‑project / per‑activity / per‑tool breakdowns, optimization health grade, model comparison, git‑yield, plan value, CSV/JSON export, and an in‑app guide).

Quick start

npx token-spend@latest

Or run from a clone:

npm install && npm start

The dashboard opens at http://localhost:3456.

Using npx? It caches packages — run npx token-spend@latest (not bare npx token-spend) to be sure you get the newest release.

What you get

• Real cost, not just tokens — every interaction priced in USD via a bundled per‑model rate table (input / output / cache), with optional currency conversion.
• GitHub AI Credits — Copilot usage in credits (1 credit = $0.01) under GitHub’s June‑2026 billing model, with a monthly burn meter and hard‑stop projection.
• Where it goes — breakdowns by project, by activity (13 categories: coding, debugging, testing, refactoring, exploration, planning, delegation, git ops…), and by tool / MCP server / subagent / skill.
• Optimization Health (A–F) — detectors for junk reads, duplicate reads, edit‑churn, context bloat, cost outliers and rarely‑used MCP servers, each with a ready‑to‑paste fix.
• Model Comparison — put two models side by side (cost/call, cost/edit, one‑shot rate, cache‑hit) to see if the pricier one earns its cost.
• Git Yield — correlates sessions with commits (productive / reverted / no‑commit / no‑git).
• Plan & Value — auto‑detects your Claude Pro/Max plan and shows the API‑equivalent value vs. the flat fee.
• Token Efficiency Score + contextual Tips — coaches you toward the habits that save tokens, flagging the ones relevant to your usage.
• Export — download any date range as JSON (full) or CSV (daily / model / activity / project / sessions).
• In‑app guide — a Help button opens a full explanation of every page, metric and calculation.

Dashboard layout

A sidebar app with three providers, each having Overview / Insights / Sessions:

| Section | Highlights | | --- | --- | | Summary | Combined totals (tokens + USD), By Tool split, Model Comparison, Export, daily chart, by‑model doughnut, Insights, Most Expensive Prompts, Sessions table | | GitHub Copilot | Interactions / estimated tokens, Tier Distribution (Lightweight vs Powerful), Usage by Mode (Agent / Ask), Credits Burn Meter, By Project / Activity / Tool Usage, Token Efficiency Score, Savings, Tips, Auto Code Review notice | | Claude Code | Plan & Value, read‑vs‑written daily chart, by‑model doughnut, By Project / Activity / Tool Usage, Optimization Health (A–F), Git Yield, Insights, Sessions | | Codex (OpenAI) | Placeholder — “coming soon” (provider not yet wired) |

Shared controls: date range + 1d/7d/30d/Month presets, Refresh, Light/Dark theme, a personalised welcome header, and Help. (The Credits Burn Meter and Plan & Value always reflect the current calendar month, independent of the date filter.)

How costs & credits are calculated

• Per‑token rates per model. cost = input×rate + output×rate + cache. Cache reads are billed at ~10% of input; cache writes at ~125%.
• Claude uses Anthropic API rates (Opus ≈ $5/$25, Sonnet ≈ $3/$15, Haiku ≈ $1/$5 per 1M in/out). The real billed token counts recorded in the session are used when present.
• Copilot uses GitHub’s published AI‑Credit rates (e.g. GPT‑5 mini $0.25/$2, Claude Sonnet $3/$15). Credits = cost ÷ $0.01. Input is estimated from text (≈4 chars/token) and output from the recorded completion count; GitHub’s real promptTokens metadata is used when available.
• Credit figures are a close estimate (shown with a ~): code completions are free and not stored locally, billing is server‑side, and agent sessions bill each internal step — so the dashboard won’t match GitHub’s counter exactly.

The default monthly credit cap is 3,500 (override with --set-credit-budget). The in‑app Help guide explains every metric in detail.

CLI options

| Flag | Default | Description | | --- | --- | --- | | --port <n> | 3456 | Dashboard port | | --no-open | false | Start the server without opening a browser | | --days <n> | 30 | Initial date window | | --data-path <p> | auto | Override the Claude data directory | | --no-copilot | false | Skip Copilot reading | | --copilot-path <p> | auto | Override the Copilot session directory | | --currency <CODE> | USD | Display currency (ECB rates, 24h cached). --currency-reset to revert | | --set-credit-budget <n> | 3500 | Monthly Copilot AI‑Credit cap | | --set-plan <id> | auto | Claude plan: pro / max5 / max20 / api (or --set-plan-budget <usd> for a custom budget; --clear-plan to reset) | | --set-name <name> | auto | Welcome‑header name (--clear-name to revert to auto‑detected) | | --export <json\|csv> | — | Write the analysis to a file and exit (--export-section daily\|model\|activity\|project\|sessions) | | --clear-cache | — | Clear the on‑disk parse cache | | --setup-copilot / --clear-copilot | — | Store / remove an optional GitHub PAT for the API mode |

Where your data is read from

| Tool | Location | | --- | --- | | Claude Code | ~/.claude/projects/**/*.jsonl on all platforms (honours $CLAUDE_CONFIG_DIR) | | GitHub Copilot | VS Code …/Code/User/workspaceStorage/<id>/chatSessions/*.jsonl (current append‑log format) |

v2.0.0 fixed the Windows Claude path (it previously looked in %APPDATA%\Claude, which holds no Code sessions) and the Copilot reader (sessions are now .jsonl, not .json).

A disk parse cache (~/.token-spend/parse-cache.json, keyed by file mtime+size) makes relaunches fast by re‑parsing only changed files.

How it works

npx token-spend
    │
    ├─ Reads  ~/.claude/projects/**/*.jsonl                 (Claude Code, all platforms)
    ├─ Reads  …/Code/User/workspaceStorage/**/chatSessions/*.jsonl   (GitHub Copilot)
    │
    ├─ Prices each turn in USD → derives GitHub AI Credits for Copilot
    ├─ Aggregates by day / model / tool / project / activity, scores & detects waste
    │  (all locally, in memory; parsed records cached on disk by file fingerprint)
    │
    └─ Opens  http://localhost:3456

Your data never leaves your machine

• No outbound network calls by default — the server binds to localhost only. (Currency rates use ECB’s public Frankfurter API and the optional Copilot PAT mode calls api.github.com; both are opt‑in.)
• No telemetry, no accounts — works entirely from local files.
• The dashboard shows a 🔒 Local only badge on every page.

Testing

npm test

356 tests across the cost engine, currency, parsers/readers, analyzers (project / activity / tool / comparison / yield / plan), optimization detectors, exporter and cache. (1 platform‑specific test skips off‑Windows.)

Project status (v2.0.0)

| Area | Status | | --- | --- | | USD cost engine + currency conversion | ✅ | | GitHub AI‑Credits model (two‑tier, burn meter, projection) | ✅ | | Real billed‑token accuracy (Copilot promptTokens, Claude usage) | ✅ | | Per‑project / per‑activity / per‑tool‑MCP‑subagent breakdowns | ✅ | | Optimization Health grade (A–F) | ✅ | | Model Comparison | ✅ | | Git Yield correlation | ✅ | | Claude plan value tracking | ✅ | | CSV / JSON export (endpoint + CLI + dashboard) | ✅ | | Disk parse cache | ✅ | | In‑app Help guide | ✅ | | Codex (OpenAI CLI) provider | 🗓 placeholder pages — coming soon | | MCP server (expose data to AI agents) | 🗓 under consideration |

Last updated: June 2026 · v2.0.0 · Author: Mohammad Karimulla Shah (Technical Architect)