Installation

This guide walks you through setting up all three components of claude-telemetry: the Supabase database, the web dashboard, and the sync agent.

Step 1: Supabase Setup

Create a Project

1. Sign up at supabase.com (free tier)
2. Create a new project — pick any name and a strong database password
3. Settings → API — copy your Project URL and service_role key

Run the Migrations

Run all migrations in order in the Supabase SQL Editor:

1. 001_initial_schema.sql
2. 002_stats_extra_unique.sql
3. 003_user_preferences.sql
4. 004_blocks.sql

Configure Auth

1. Go to Authentication → URL Configuration
2. Set your Site URL to your dashboard URL (you'll get this after deploying)
3. Add the same URL to Redirect URLs
4. Go to Authentication → Email Templates and customize if desired

Step 2: Deploy the Dashboard

Clone and Install

git clone https://github.com/RyanTech00/claude-telemetry.git
cd claude-telemetry/dashboard
npm install

Create Project and Configure Secrets

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,friend@email.com"

Build and Deploy

npm run build
npx wrangler pages deploy dist

After deployment, Cloudflare will give you a URL like claude-telemetry.pages.dev. Go back to Supabase and update your Site URL and Redirect URLs with this address.

Step 3: Install the Agent

The agent needs to be installed on each PC where you use Claude Code.

Install from PyPI (recommended)

# Install dependencies
npm install -g ccusage ccost

# Install cc-telemetry
pip install cc-telemetry

# Run the setup wizard
cc-telemetry setup

# Verify everything is working
cc-telemetry doctor

The setup wizard will:

1. Check that ccusage and ccost are available
2. Prompt for your Supabase URL, service key, and machine name
3. Configure statusline, hooks, MCP server, and daemon
4. Run an initial sync to populate the dashboard

Configuration is saved to ~/.claude-telemetry/config.json.

Minimal setup

Use cc-telemetry setup --minimal if you only want the base config without hooks, MCP, or statusline.

Verify

Run the health check:

$ cc-telemetry doctor

Claude Telemetry — Health Check

  OK  ccusage              available via npx
  OK  ccost                0.3.1
  OK  Config valid         windows-pc-04apr (a2338a3f...)
  OK  Supabase reachable   connected
  OK  Statusline configured
  OK  Hooks configured     SessionEnd + Stop
  OK  MCP server registered
  OK  Daemon running
  OK  Last sync            2026-04-09 00:08:05
  OK  Hook sync active     862m ago

  10/10 checks passed

Each failed check includes an actionable hint to fix it. Then open your dashboard — you should see data appearing.

Source Install (advanced)

If you prefer to install from source instead of PyPI:

git clone https://github.com/RyanTech00/claude-telemetry.git
cd claude-telemetry/agent
python3 -m venv venv
source venv/bin/activate  # Windows: .\venv\Scripts\Activate
pip install -e .
cc-telemetry setup

Troubleshooting

Quick diagnostics

Run cc-telemetry doctor first — it checks 10 common issues and gives actionable hints for each failure.

Agent can't connect to Supabase

• Verify your Supabase URL and API key in ~/.claude-telemetry/config.json
• Ensure your network allows outbound HTTPS connections
• Check Supabase dashboard → Logs for any rejected requests

Dashboard shows "Unauthorized"

• Make sure your email is in the ALLOWED_EMAILS whitelist
• Check that the Supabase Site URL matches your dashboard URL
• Try clearing your browser cookies and logging in again

No data after sync

• Run cc-telemetry sync --verbose for detailed output
• Verify Claude Code has been used on this machine (check ~/.claude/projects/)
• Run cc-telemetry local --daily to inspect local data without syncing

Service won't start

• Linux: Check journalctl -u cc-telemetry for errors
• macOS: Check launchctl list | grep claude-telemetry and Console.app
• Windows: Check Event Viewer → Application logs