AI Token Spend

Personal AI token usage intelligence for developers. One command, zero setup, 100% local.

AI Token Spend reads your Claude Code and GitHub Copilot session files directly from disk, aggregates your token usage by day and model, and opens a browser dashboard — all on localhost. It surfaces plain-English insights about where your tokens went and which sessions drove the most usage. Nothing is transmitted anywhere: no API calls, no telemetry, no accounts.

Quick start

npx token-spend

Or install locally:

npm install && npm start

Dashboard

The dashboard is a three-tab interface at http://localhost:3456:

Summary tab

A combined view across both tools — total tokens, session count, daily usage chart, by-model doughnut, all sessions table, and insights from both Claude and Copilot.

GitHub Copilot tab

Copilot-only view — interaction count, estimated token total, models used, daily chart, Copilot-specific insights, and a filterable sessions table. Shows a friendly empty state with the exact path being checked if no Copilot sessions are found.

Claude Code tab

Claude-only view — total tokens, session count, cache savings, dual-axis daily chart (Read vs Written), Claude model breakdown doughnut, and Claude-specific insights.

All three tabs share a single data fetch and support search, sorting, and pagination (10 / 50 / 100 per page). The tab bar sticks below the header as you scroll.

| Section | Description | | ------------------- | --------------------------------------------------------------------------- | | Overview cards | Total tokens, sessions, messages sent, and output tokens with context | | By Tool row | Side-by-side Claude vs Copilot token totals and percentages | | Insights | 4–6 plain-English observations, expandable for detail | | Usage Breakdown | Daily bar chart + By Model doughnut, filtered per tab | | Sessions table | Sortable, searchable, paginated — date, prompt, model, tokens, read/written |

CLI options

| Flag | Default | Description | | ----------------- | ------- | ------------------------------------------------------ | | --port | 3456 | Dashboard port | | --no-open | false | Start server without opening browser | | --days | 30 | Number of days to analyse | | --data-path | auto | Override Claude data directory path | | --sprint-start | none | Sprint start date YYYY-MM-DD for sprint-period stats | | --no-copilot | false | Skip Copilot reading entirely | | --copilot-path | auto | Override Copilot session files directory | | --copilot-mode | local | Force local (VS Code files) or api (GitHub API) | | --setup-copilot | — | Interactive setup to store a GitHub PAT for Option B | | --clear-copilot | — | Remove stored GitHub PAT from config |

GitHub Copilot — two modes

Option A — Local files (default, zero setup)

AI Token Spend reads GitHub Copilot Chat session files stored by VS Code:

| OS | Path | | ------- | --------------------------------------------------------------------------------------------- | | Windows | %APPDATA%\Code\User\workspaceStorage\{workspace-id}\chatSessions\*.json | | macOS | ~/Library/Application Support/Code/User/workspaceStorage/{workspace-id}/chatSessions/*.json | | Linux | ~/.config/Code/User/workspaceStorage/{workspace-id}/chatSessions/*.json |

Token counts are estimated (1 token ≈ 4 characters) and displayed with a ~ prefix. All estimated values carry an estimated: true flag internally.

Option B — GitHub API (optional, exact counts)

Run once to store a GitHub Personal Access Token:

token-spend --setup-copilot

The tool prompts for your PAT, validates it against the GitHub API, and stores it locally at:

• Windows: %APPDATA%\TokenSpend\config.json
• Mac/Linux: ~/.token-spend/config.json (chmod 600)

With a valid PAT, AI Token Spend fetches real daily token counts from api.github.com. If the API call fails for any reason it falls back to Option A automatically.

To remove a stored token:

token-spend --clear-copilot

How it works

npx token-spend
    │
    ├─ Reads  ~/.claude/projects/**/*.jsonl              (Claude Code — Mac/Linux)
    │         %APPDATA%\Claude\projects\**\*.jsonl       (Claude Code — Windows)
    │
    ├─ Reads  ~/...workspaceStorage/**/chatSessions/*.json  (Copilot — Option A)
    │     or  api.github.com/copilot_internal/user/usage    (Copilot — Option B)
    │
    ├─ Merges + analyses token usage locally, in memory
    │
    └─ Opens  http://localhost:3456

Your data never leaves your machine

• No outbound network calls — the server binds to localhost only (except when Option B is explicitly enabled, which only calls api.github.com)
• No telemetry or analytics — zero tracking of any kind
• No accounts required — works entirely from local files by default
• PAT never logged or transmitted — stored only in your local config file
• The dashboard displays a privacy confirmation on every page load

Compatibility

| Environment | Status | | ----------------------------- | ----------------- | | Windows 10/11 (AWS WorkSpace) | ✅ Primary target | | macOS | ✅ Supported | | Linux | ✅ Supported | | Node.js 18+ | Required |

Testing

node --test test/reader.test.js test/parser.test.js test/analyzer.test.js test/copilot.test.js

167 tests, 0 failures. 2 skipped (Windows-only path tests, skipped on Mac/Linux).

Project status

Layer 1 — Claude Code dashboard ✅ Complete

• Cross-platform path resolution for Claude session files (Windows, Mac, Linux)
• JSONL session parsing and usage extraction
• Daily aggregation, model breakdown, session ranking
• Insight engine (busiest day, top model, long-session warnings, cache savings)
• Express.js server + vanilla HTML/CSS/JS dashboard
• Date range filtering, sortable sessions table

Layer 2 — GitHub Copilot integration ✅ Complete

All 11 development steps shipped:

1. copilotPathResolver.js — detects VS Code workspaceStorage path cross-platform
2. copilotReader.js — reads all chatSessions/*.json files with 50 MB size guard
3. copilotParser.js — parses Copilot Chat session JSON format (prompt parts, model, toolCallRounds response)
4. copilotTokenEstimator.js — estimates input/output tokens from text length (ceil(len/4))
5. toolComparison.js — merges Claude + Copilot records, tags by tool, sorts by timestamp
6. Dashboard — three-tab layout (Summary / GitHub Copilot / Claude Code), By Tool row, Tool column in sessions table, Copilot dataset in daily chart, per-tab doughnut charts
7. insightEngine.js — Copilot insights: tool split %, switch detection, not-detected notice
8. configManager.js — reads/writes ~/.token-spend/config.json, chmod 600 on Mac/Linux
9. copilotApiReader.js — GitHub API integration with individual + org endpoint fallback
10. copilotSetup.js — interactive --setup-copilot CLI flow with hidden PAT input and validation
11. src/index.js — async orchestrator with all new CLI flags, setup/clear routing, merged pipeline

Dashboard improvements shipped alongside Layer 2:

• Three-tab navigation with localStorage persistence
• Sticky header + tab bar (header locks at top, tab nav locks below header on scroll)
• Per-tab By Model doughnut charts (filtered to each tool's models)
• Pagination on all three session tables (10 / 50 / 100 per page)
• Light/Dark theme toggle with 🌍 globe pill

Roadmap

| Layer | Feature | Status | | ----- | --------------------------------- | ----------- | | 1 | Claude Code usage dashboard | ✅ Complete | | 2 | GitHub Copilot integration | ✅ Complete | | 3 | Model recommendation engine | 🗓 Planned | | 4 | Prompt optimisation suggestions | 🗓 Planned | | 5 | Windows / AWS WorkSpace hardening | 🗓 Planned |

Layer 3 — Model recommendation engine (planned)

Analyse historical usage patterns to suggest which Claude model (Haiku / Sonnet / Opus) or Copilot model is most cost-efficient for different task types. Surface as actionable insights in the dashboard.

Layer 4 — Prompt optimisation suggestions (planned)

Detect high token-count sessions and suggest prompt strategies that reduce context size without losing quality. Tie into the existing insight engine.

Layer 5 — Windows / AWS WorkSpace hardening (planned)

Targeted testing and fixes for the primary deployment environment — Windows 10/11 AWS WorkSpace machines. Includes path edge cases, APPDATA quirks, and installer/distribution packaging.

Under discussion (not yet committed)

• Export / reporting — CSV or JSON export of usage data for personal record-keeping (privacy-preserving, local only)
• Sprint budgeting — set a token budget per sprint and show a progress bar toward it
• Multi-user aggregate view — opt-in aggregation across a team (requires a shared local server, complex privacy tradeoffs — no decision made)
• VS Code extension — surface token usage directly inside VS Code as a status bar item
• Cursor / Windsurf support — extend Layer 2 reader pattern to other AI coding tools

Last updated: April 2026 | Author: Mohammad Karimulla Shah (Technical Architect)