claude-telemetry — Claude Code Usage Tracking

Claude Code Usage Tracking

Multi-PC aggregation dashboard for Claude Code power users

Multi-PC Aggregation

Auto-sync agent on each machine pushes usage data to a central Supabase database. See total spending across all your workstations.

Web Dashboard

Dark-mode React dashboard with interactive charts. Filter by machine, project, model, and time period.

5-Hour Blocks

Track Claude Code billing windows with burn rate, projections, and cross-machine overlap detection.

Zero Exposed Keys

Cloudflare Workers proxy all API calls. No secrets in your frontend bundle. Magic link auth with email whitelist.

Plan vs API Cost

See how much your subscription saves you. Compare plan cost against equivalent API pricing.

Deploy in Minutes

Wazuh-style deploy page generates copy-paste install commands per OS. Free hosting on Cloudflare + Supabase.

The Problem

CLI tools like ccusage and ccost are excellent for tracking Claude Code usage — but they're single-machine tools.

If you use Claude Code on 2+ PCs (work laptop, home desktop, cloud VM), you have no unified view of your total spending. The Anthropic rate limits are per account, not per machine — you need to see everything together.

No idea how close you are to your 5-hour block limit across machines
No way to compare daily spend between workstations
No centralized dashboard to share with your team or manager
No historical trends across your entire usage footprint

The Solution

claude-telemetry is the aggregation and visualization layer on top of tools like ccusage.

Each PC runs a lightweight Python agent that calls ccusage to extract usage data from Claude Code's logs and syncs it to Supabase every 15 minutes. The agent does no custom JSONL parsing — it delegates that to ccusage and focuses only on multi-PC aggregation and centralized sync.

Quick Start

Get up and running in 3 steps:

1. Setup Supabase (free tier)

Create a project on supabase.com and run the SQL migrations:

-- Run in Supabase SQL Editor
-- Full schema: /guide/installation
CREATE TABLE IF NOT EXISTS usage_data (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  machine_id TEXT NOT NULL,
  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  -- ... see full migration in installation guide
);

2. Deploy the Dashboard

git clone https://github.com/RyanTech00/claude-telemetry.git
cd claude-telemetry/dashboard
npm install
npx wrangler pages project create claude-telemetry
npx wrangler pages secret put SUPABASE_URL        # paste Project URL
npx wrangler pages secret put SUPABASE_SERVICE_KEY # paste service_role key
npx wrangler pages secret put ALLOWED_EMAILS       # e.g. "you@email.com"
npm run build
npx wrangler pages deploy dist

3. Install the Agent on Each PC

cd claude-telemetry/agent
python3 -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\Activate
pip install -e .
claude-tracker setup
claude-tracker sync --verbose
claude-tracker install-service  # auto-sync every 15min

The agent runs as a background service and syncs automatically. See the full installation guide for details.

Comparison

Feature	claude-telemetry	ccusage	ccost	CC_Dashboard
Daily/Monthly/Session reports	✅	✅	✅	✅
5-Hour Blocks	✅	✅	✅	❌
Weekly reports	✅	✅	❌	❌
Web dashboard	✅	❌	❌	✅
Multi-PC aggregation	✅	❌	❌	❌
Auto-sync daemon	✅	❌	❌	❌
Deploy page (Wazuh-style)	✅	❌	❌	❌
Auth + email whitelist	✅	❌	❌	❌ (API key)
Plan vs API cost	✅	❌	❌	✅
Currency conversion	❌	❌	❌	✅
Docker support	❌	❌	❌	✅
Rate limit predictor	✅	❌	❌	❌
Project budgets	✅	❌	❌	❌
Cross-machine burn rate	✅	❌	❌	❌
MCP Server	🔜 v0.3	✅	❌	❌
Rate limit % (5h/1w)	✅	❌	✅	❌
Zero cost hosting	✅	N/A	N/A	❌
Open source	✅ MIT	✅ MIT	✅ MIT	✅ MIT

claude-telemetry uses ccusage and ccost as data layers. We're the aggregation and visualization layer on top.

What Shipped in v0.2.0

✅ Plan vs API Cost — Compare subscription cost against API-equivalent pricing
✅ Weekly Reports — Daily/Weekly toggle with stacked bar charts
✅ 5-Hour Blocks — Multi-PC block timeline with burn rate and overlap detection
✅ Rate Limit Progress Bars — Visual 5-hour and weekly rate limit usage
✅ Usage Pace Calculator — Daily averages with trend detection
✅ Project Budgets — Per-project spending limits with progress bars and alerts

See the full Roadmap for v0.3.0 and beyond.

Support

If claude-telemetry saved you from rate limit blindness or helped you understand your Claude Code costs, consider supporting the project:

Star the repo on GitHub to help others discover claude-telemetry.