claude-spend

See where your Claude Code tokens go. One command. Local dashboard. No setup.

npx @mpalermiti/claude-spend

Reads your local Claude Code session data (~/.claude/) and shows you exactly where your tokens go. Everything runs locally. Nothing leaves your machine.

The ROI Multiplier

Your Claude Code subscription hides how much API-equivalent value you're actually using. claude-spend reveals it. It detects your plan (Pro, Max 5x, Max 20x) from your local Claude Code config, and the dashboard shows your multiplier — how many times over you're getting your money's worth.

26.7x value from your $200/mo plan

This is the stat that makes you feel good about your subscription. And the one your followers will screenshot.

Related MCP server: tokenscope

What's in v3

Install

npx @mpalermiti/claude-spend

CLI flags:

--port <port>   Custom port (default: 3456)
--no-open       Don't auto-open browser
--mcp           Run as MCP server (stdio)
--help          Show help

Dashboard Sections

1. Hero — API-equivalent cost at a glance, trend delta, ROI multiplier badge

2. Stat cards — Total tokens, conversations, messages, cache hit rate (color-coded)

3. Charts — Daily stacked bars with 7-day moving average and cumulative cost overlay, model donut with hover tooltips

4. Activity heatmap — When you code, hour by day of week

5. Insights — Featured top insight + expandable list of 12 automated recommendations

6. Tool usage — Horizontal bars showing which tools Claude calls most

7. Projects — Per-project token breakdown with expandable prompt details

8. Most expensive prompts — Top 20 messages ranked by token usage

9. All sessions — Sortable, searchable table with click-to-drill-down

10. Session drill-down — Per-turn cost curve, context growth, turn-by-turn token breakdown

Keyboard Shortcuts

MCP Server

Add this to ~/.claude/settings.json and Claude can query spend data during any conversation:

{
  "mcpServers": {
    "claude-spend": {
      "command": "npx",
      "args": ["@mpalermiti/claude-spend", "--mcp"]
    }
  }
}

Six tools: get_spend_summary, get_top_sessions, get_project_breakdown, get_insights, get_daily_trend, get_quota. The first five accept optional from/to date params.

Report and Quota Modes

For scripts, cron jobs, and agents that want numbers without a browser:

claude-spend --report --project myapp --trend-days 7          # markdown, grouped by project
claude-spend --report --sessions build#1:<uuid>,build#2:<uuid>  # one row per session id
claude-spend --report --from 2026-09-01 --to 2026-09-07 --json  # machine-readable
claude-spend --quota                                            # "session 58% · weekly 28%"

--sessions takes label:id pairs (label optional). Subagent and workflow transcripts fold into the session that spawned them, so one row is the whole job. Launch a job with claude -p ... --session-id $(uuidgen) and you can report on exactly that job afterwards.

--quota reads your subscription's rolling windows (5-hour session, 7-day weekly) from the same endpoint Claude Code's /usage uses. It is best-effort and macOS-first (the token lives in the login keychain); --report includes it unless you pass --no-quota.

How It Works

Claude Code writes JSONL session files to ~/.claude/projects/. This tool parses them, calculates API-equivalent costs per model (with cache write/read pricing), aggregates by day/model/project, and generates insights. The cost numbers represent what the usage would cost at API rates — not what you pay on a subscription. That gap is your ROI.

Accuracy notes (3.1): Claude Code writes one JSONL line per content block and repeats the usage on each, so responses are deduped by message id. Transcripts nested under <session>/subagents/** (including workflow agents) are read and attributed to their parent. Pricing covers the Claude 5 family (Opus 5, Sonnet 5, Fable 5.1) and prices 1-hour cache writes at 2× input, which is what Claude Code uses. Set CLAUDE_CONFIG_DIR to point at a different data dir.

Origin

Forked from claude-spend by Aniket Parihar. I kept the core JSONL parser concept, then rebuilt everything else: the dashboard, date filtering, analytics engine, insights, drill-downs, heatmap, share card, keyboard nav, MCP server, and the design. MIT license.