Skip to content
Back to site
Case Study2026

Ledger — Claude Code Cost Dashboard

Real-time cost tracking for Claude Code sessions. Parse JSONL conversations, compute exact token costs per session, expose via REST API. Runs on Raspberry Pi with TUI and web dashboard.

Timeline

2026

Platform

TypeScript

Links

Source Codenpm Package
TypeScriptNode.jsExpressVitestCLICost TrackingOpen Source
Ledger — Claude Code Cost Dashboard

Ledger solves a real problem: Claude Code runs 24/7 on my Raspberry Pi, but I had no visibility into daily costs in real-time. The Anthropic dashboard exists, but requires a browser tab. What I wanted was a CLI command, a REST API, and a local web dashboard.

Ledger parses Claude Code's JSONL session files from ~/.claude/projects/, computes exact token costs per conversation (accounting for cache writes, reads, and model pricing), and exposes the data via REST API. It runs as a service and speaks to Telegram.

What It Does

  • Parses JSONL conversations — Claude Code writes every session to a local file. No external API needed.
  • Computes exact costs — Handles input tokens, output tokens, cache writes (1h/5m TTL), cache reads, and per-model pricing.
  • Exposes a REST API — Query costs by session, project, date, or model via HTTP.
  • TUI dashboard — Terminal UI for quick cost summaries (no browser required).
  • Web dashboard — Interactive charts, trends, and detailed breakdowns.
  • Telegram integration — Type /cost in Telegram and get today's spend in under a second.

Architecture

  • src/currency.ts — Pricing tables per model (Opus, Sonnet, Haiku, etc.), with fallback pricing.
  • server/pricing.ts — Cost calculation logic. Handles cache multipliers: 3.75x for 1h writes, 1.25x for 5m, 0.10x for reads.
  • server/parser/ — JSONL parsing, conversation aggregation, project slug extraction.
  • server/analyzer/ — Session insights: cache hit rates, model usage, web search counts.
  • server/server.ts — Express API (runs on port 4200).
  • bin/ledger.ts — CLI entry point with TUI (chalk + ink).

Usage

CLI

npm install -g @rezaiyan/ledger

ledger status                 # Today's spend
ledger status --short         # Compact view
ledger sessions              # All conversations
ledger last                  # Most recent session

REST API

npm run server:start

# Available endpoints:
GET  /api/sessions           # All parsed conversations
GET  /api/sessions/:id       # Single session details
GET  /api/costs/today        # Today's total cost
GET  /api/costs/by-model     # Cost breakdown by model
GET  /api/projects           # Cost per project

Development

npm install
npm run dev              # Watch server + web bundler
npm run test            # Run tests (Vitest)
npm run test:ui         # Test UI dashboard
npm run build           # Compile + bundle web frontend

Testing

Ledger includes comprehensive unit and integration tests:

  • 20 unit tests for pricing calculations, model matching, cache multipliers, and edge cases.
  • 12 integration tests for the full JSONL parsing → cost aggregation pipeline.
  • All tests run with Vitest and cover accuracy, error handling, and real-world workflows.

Why It Matters

Claude Code stores complete session data locally. Ledger extracts insights from that data without external APIs, without exposing tokens, and without any latency. It runs offline on a Raspberry Pi and speaks to your tools (Telegram, dashboards, analytics pipelines).

The pricing model is subtle — get cache math wrong and your estimates can be off by 20-40%. Ledger handles the detailed breakdown with a fallback to older conversation formats.

Deployment

Ledger runs as a systemd service on the Pi: 

sudo cp ledger.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl start ledger
sudo systemctl enable ledger

Access the web dashboard at http://localhost:4200 or query the API from anywhere on your network.

Blog Post

For the full story — why I built this, how the pricing logic works, and why cache math is tricky — read the case study.

Open Source