Claude Token Tracker

Real-time dashboard for Claude Code token usage, API-equivalent cost estimation, and coding activity tracking.

Quick Start

git clone https://github.com/pepperonas/claude-token-tracker.git
cd claude-token-tracker
npm install
npm start

Open http://localhost:5010

Highlights

• 25+ interactive charts across 10 tabs with real-time SSE updates
• Claude API tab — Anthropic Admin API usage/cost dashboard: budget tracking with progress bar, 4 KPIs (total cost, tokens, avg cost/day, cache efficiency), daily cost/token charts by model, model distribution doughnut, cumulative cost trend. Per-API-key breakdown: horizontal stacked bar chart showing cost per key by model, daily cost timeline per key, key comparison table (tokens, input, output, cache %, calculated cost, last used), token history timeline (stacked area). Costs per key calculated via model pricing since the cost API doesn't support group_by api_key_id. Key names resolved via /v1/organizations/api_keys. AES-256-GCM encrypted key storage, SWR caching with configurable TTL
• GitHub Integration — SWR caching, billing with plan detection & percentages, code statistics (LOC by repo), PR Code Impact, Actions Usage by Repository, contribution heatmap
• Tool Cost Attribution — proportional cost/token distribution per tool, MCP server breakdown (auto-detected via mcp__ prefix), sub-agent tracking (via /subagents/ path), cost-over-time chart, enhanced table with Type/Cost/Tokens columns
• Project Detail Dialog — click any project in chart or table to open a detail modal with 6 KPIs (tokens, cost, sessions, messages, total time, net lines), daily token chart, model distribution doughnut, top tools, sessions list, and JSON export to clipboard
• Rate-Limit Tracking — automatic detection of Claude Code rate-limit events from JSONL logs, daily aggregation, KPI card, backfill for historical data
• Period navigation — prev/next arrows beside date picker jump by selected period duration
• Productivity tab — Tokens/Min, Lines/Hour, Cost/Line, Cache Savings, Code Ratio with trend indicators
• Period comparison — inline pill selector (Off / Prev. Period / Last 7d / 30d / 90d / Custom) compares two periods side-by-side with 8 metrics, delta %, and color-coded indicators
• HTML export — mobile-responsive interactive snapshot with Chart.js, 8 tabs, 12+ charts, and sortable tables. Optimized for phones (412px+) with adaptive layouts
• Global comparison — compare your stats against the average of all users (multi-user mode)
• 700 achievements — gamification system across 14 categories with 5 tiers, tier-based points, timeline chart, daily unlock stats, and real-time unlock notifications via SSE
• Lines of Code tracking — Write (green), Edit (yellow), Delete (red) with adaptive hourly/daily chart
• Multi-device tracking — track usage across multiple machines (MacBook, VPS, Desktop), per-device API keys, device switcher in dashboard, aggregated "All Devices" view, click-to-rename devices, OS-selectable install commands
• Multi-user mode — GitHub OAuth, per-user data isolation, Sync Agent with one-click install (macOS/Linux/Windows)
• Token breakdown — Input, Output, Cache Read, Cache Create with per-type API-equivalent cost estimation
• Share API — secure external API for sharing project-specific token usage data with clients. Share tokens (48-char hex, 192-bit entropy) expose sanitized project data (tokens, cost, sessions, code lines, daily breakdown) via public endpoints. Admin key authentication for share management, rate limiting (30 req/min/IP), CORS restrictions, and optional expiry. Used by OPS for customer transparency dashboards. Settings UI shows Share Admin Key with copy button.
• Database download — download the full SQLite database from Settings for local backup or analysis
• 151 automated tests — unit, integration, and multi-user API tests
• Zero-framework frontend — vanilla JS, 2 runtime dependencies, no build step

Screenshots

Overview — KPI cards, token breakdown, lines of code, daily charts	Sessions — sortable table with project, model, duration, tokens, cost
Projects — per-project statistics and cost breakdown	Tools — tool cost attribution, MCP server breakdown, sub-agent tracking
Models — model usage, daily tokens by model, cost breakdown	Insights — cache efficiency, stop reasons, lines of code chart
Productivity — efficiency metrics with period comparison	Achievements — 700 achievements across 14 categories with 5 tiers

Mobile (iPhone 16 — 393px)

Overview	Insights	Productivity	Achievements

Architecture

~/.claude/projects/**/*.jsonl
    -> Parser (incremental byte-offset, dedup by message ID)
    -> SQLite (WAL mode, 10 tables)
    -> Aggregator (in-memory pre-computed maps)
    -> HTTP Server (50+ JSON endpoints + SSE)
    -> Frontend (Chart.js, vanilla JS, i18n DE/EN)

Multi-user mode:

Sync Agent (client) -> POST /api/sync (API key auth)
    -> Per-user SQLite storage
    -> AggregatorCache (lazy loaded, incremental sync, 30min eviction)
    -> GitHub OAuth sessions

Share API (external integration):

OPS -> POST /api/shares (admin key auth) -> project_shares table
Customer browser -> GET /api/public/share/:token -> sanitized project data

Tech Stack

Share API

Endpoints

Security

• Share tokens: 48-char hex (24 bytes / 192-bit cryptographic randomness)
• Admin key: 64-char hex, stored in .env, required for management endpoints
• Rate limiting: 30 requests/minute per IP on public endpoint
• CORS: restricted to configured origins (ops.celox.io, tracker.celox.io)
• No internal paths exposed, no project enumeration possible
• Optional expiry dates on share tokens

Setup

# Add to .env
SHARE_ADMIN_KEY=your-64-char-hex-key
# Or generate in Settings -> Share API -> "Neu generieren"

Integration with OPS

1. Open Token Tracker -> Settings -> Share API
2. Copy Tracker URL and Share Admin Key
3. Add to OPS .env: TOKEN_TRACKER_BASE_URL and TOKEN_TRACKER_ADMIN_KEY
4. In OPS: Edit customer -> "Projekt verknuepfen" -> select project
5. Customer detail page shows KI-Nutzung tab with charts, costs, and sessions

Public Response Format

{
  "label": "Project Label",
  "summary": { "total_cost", "total_sessions", "lines_written", "..." },
  "daily": [{ "date", "messages", "cost", "lines_written", "..." }],
  "sessions": [{ "start", "end", "duration_min", "cost", "model", "..." }]
}

Links

• Try it: tracker.celox.io
• Author: Martin Pfeffer | GitHub
• License: MIT

If you find this project useful, consider supporting its development: