Getting Started
claude-telemetry is a centralized usage tracking and analytics platform for Claude Code. It aggregates data from multiple machines into a single web dashboard.
Who Is This For?
- Power users running Claude Code on 2+ machines who need a unified cost view
- Team leads who want visibility into Claude Code usage across the team
- Budget-conscious developers who want to track spending and predict rate limits
Prerequisites
| Requirement | Version | Notes |
|---|---|---|
| Node.js | 18+ | For the dashboard |
| Python | 3.11+ | For the sync agent |
| Supabase account | Free tier | Database + auth |
| Cloudflare account | Free tier | Dashboard hosting + worker proxy |
Architecture Overview
claude-telemetry has three components:
1. Supabase (Database + Auth)
Supabase provides the PostgreSQL database that stores all usage data, plus authentication via magic links with an email whitelist. The free tier is more than enough for personal use.
2. Dashboard (Cloudflare Pages)
A React web application deployed to Cloudflare Pages. It communicates with Supabase through a Cloudflare Pages Functions proxy — no API keys are ever exposed in the frontend.
Dashboard pages:
| Page | Description |
|---|---|
| Overview | Total cost, daily chart, model pie, machine cards |
| Daily | Stacked area chart, top 10 days, hour heatmap |
| Projects | Cost by project, pie distribution, full table |
| Models | Opus/Sonnet/Haiku breakdown, mix over time, savings alert |
| Machines | Per-machine cards, comparison chart, status badges |
| Deploy | Generate agent install commands with one-click copy |
| Sessions | Paginated table with sorting and filters |
| Insights | Rate projections, optimization tips, trend analysis |
| Settings | Machine management, export, alert thresholds |
3. Agent (Each PC)
A lightweight Python daemon that calls ccusage to extract usage data from Claude Code's logs and syncs it to Supabase. The agent does no custom JSONL parsing — it delegates that to ccusage and focuses only on multi-PC aggregation and centralized sync. It runs as a background service (systemd on Linux, launchd on macOS, Task Scheduler on Windows) and syncs every 15 minutes by default.
Tech Stack
| Component | Technology | Hosting |
|---|---|---|
| Agent | Python 3.11+, ccusage | Local (each PC) |
| Dashboard | React 18, Vite, TailwindCSS, Recharts | Cloudflare Pages |
| Database | PostgreSQL | Supabase (free tier) |
| Auth | Magic Link | Supabase Auth |
| API Proxy | Pages Functions | Cloudflare Workers |
Next Steps
Ready to set up claude-telemetry? Head to the Installation Guide.