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. Select your plan ($100 or $200/mo), 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.

What's in v3

| Feature | Original | v3 | |---------|----------|-----| | Token usage chart | Basic bar chart | Stacked bars + 7-day moving average + cumulative cost line | | Date filtering | None | 6 presets + custom range | | Cost estimation | None | Full API-equivalent cost with per-model pricing | | ROI multiplier | None | Plan-aware, shows Nx value vs subscription | | Trend comparison | None | Cost/token delta vs previous equivalent period | | Activity heatmap | None | Hour x day-of-week grid with peak callout | | Session drill-down | None | Per-turn cost chart, context growth, token breakdown | | Chart tooltips | None | Hover daily bars and donut for detailed breakdowns | | Smart insights | None | 12 automated insights (vague prompts, marathon sessions, model waste) | | Project breakdown | None | Per-project tokens with expandable prompt drawers | | Tool usage | None | Top 15 tools, ranked color gradient | | Share card | None | 1200x630 PNG with hero cost, ROI badge, stats | | Keyboard navigation | None | j/k navigate, Enter drill down, / search, d dark mode | | Dark mode | None | Full dark theme with CSS variable system | | MCP server | None | 5 tools — Claude can query its own spend | | Design | Basic HTML table | Emerald identity, Plus Jakarta Sans + JetBrains Mono, dot grid, micro-interactions |

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

| Key | Action | |-----|--------| | j / k | Navigate sessions | | Enter | Open drill-down | | Escape | Close drill-down / modals | | / | Focus search | | d | Toggle dark mode | | r | Refresh data |

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"]
    }
  }
}

Five tools: get_spend_summary, get_top_sessions, get_project_breakdown, get_insights, get_daily_trend. All accept optional from/to date params.

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.

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.