claude-telemetry

Centralized Claude Code usage tracking across multiple PCs

What is this?

CLI tools like ccusage and ccost are single-machine. If you use Claude Code across multiple PCs, you have no unified view of your total spending.

claude-telemetry solves this with an Elastic/Wazuh-style architecture: a lightweight Python agent on each PC auto-syncs usage data to a central Supabase database, and a React dashboard shows everything aggregated with filters by machine, project, model, and time period.

The agent does no custom JSONL parsing — it calls ccusage as the parsing/pricing layer and focuses only on multi-PC aggregation and centralized sync.

Features

• Multi-PC aggregation with per-machine tracking
• Auto-sync daemon (Elastic/Wazuh style agent)
• Dark-mode dashboard with interactive charts (Recharts)
• 5-hour block tracking with active block card, burn rate, and multi-PC timeline
• Plan vs API cost comparison (Pro/Max 5x/Max 20x/Custom)
• Rate limit progress bars (5-hour + weekly windows)
• Usage pace calculator with trend detection
• Project budget tracker with alerts at 90%/100%
• Weekly usage reports with daily/weekly toggle
• Cross-machine usage pace comparison
• Model mix analysis (Opus/Sonnet/Haiku breakdown)
• Supabase Auth (magic link login) with email whitelist
• Cloudflare Workers proxy (zero exposed keys in frontend)
• Deploy page with copy-paste agent install commands
• Statusline auto-setup for rate limit tracking
• Export data as CSV/JSON
• Uses existing tools (ccusage) — no custom JSONL parsing

Quick Start

Step 1 — Supabase (free tier)

1. Create account at supabase.com
2. New Project — choose name and region
3. SQL Editor — paste and run each migration in order:
   1. supabase/migrations/001_initial_schema.sql
   2. supabase/migrations/002_stats_extra_unique.sql
   3. supabase/migrations/003_user_preferences.sql
   4. supabase/migrations/004_blocks.sql
4. Authentication > URL Configuration:
   • Site URL: https://your-app.pages.dev
   • Redirect URLs: add same URL
5. Settings > API — copy Project URL and service_role key

Step 2 — Dashboard (Cloudflare Pages)

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. "[email protected],[email protected]"
npm run build
npx wrangler pages deploy dist

Step 3 — Agent (each PC)

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

Architecture

Dashboard Pages

CLI Reference

Security

• Dashboard access: Only emails listed in ALLOWED_EMAILS can log in. Set via:

  npx wrangler pages secret put ALLOWED_EMAILS
  # value: "[email protected]" or "[email protected],[email protected]"
  

• API proxy: All Supabase keys are server-side only (Cloudflare Workers). Zero secrets in the browser bundle.
• Agent auth: Each machine uses a unique API key stored locally in ~/.claude-telemetry/config.json.
• RLS: Row-Level Security ensures each user only sees their own machines and data.

Uninstall

To completely remove claude-telemetry from all services:

Step 1 — Remove agent (each PC)

# Stop and remove the service
claude-telemetry uninstall-service

# Remove config and data
claude-telemetry uninstall

# Or manually:
# Windows: rd /s /q %USERPROFILE%\.claude-telemetry
# Linux/macOS: rm -rf ~/.claude-telemetry

# Remove the package
pip uninstall claude-telemetry
# Delete the repo folder

Step 2 — Delete Cloudflare Pages

npx wrangler pages project delete claude-telemetry
# Or: Cloudflare Dashboard > Workers & Pages > claude-telemetry > Settings > Delete project

Step 3 — Delete Supabase project

Supabase Dashboard > Project Settings > General > Delete project.
This permanently deletes all data.

After these 3 steps, nothing remains — no data, no services, no secrets.

Tech Stack

Support

If this tool saved you from rate limit blindness, consider buying me a coffee:

Or just star the repo — it helps a lot!

Star History

License

MIT — see LICENSE

Author

Ryan Barbosa — [email protected]