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 Migration

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

The initial migration creates the usage_data table, indexes, and Row-Level Security policies:

CREATE TABLE IF NOT EXISTS usage_data (
  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
  machine_id TEXT NOT NULL,
  machine_name TEXT,
  session_id TEXT,
  timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
  model TEXT,
  input_tokens BIGINT DEFAULT 0,
  output_tokens BIGINT DEFAULT 0,
  cache_read_tokens BIGINT DEFAULT 0,
  cache_write_tokens BIGINT DEFAULT 0,
  cost_usd NUMERIC(10, 6) DEFAULT 0,
  project_path TEXT,
  duration_seconds INTEGER,
  metadata JSONB DEFAULT '{}'::jsonb,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

-- Create indexes for common queries
CREATE INDEX idx_usage_data_machine ON usage_data(machine_id);
CREATE INDEX idx_usage_data_timestamp ON usage_data(timestamp);
CREATE INDEX idx_usage_data_session ON usage_data(session_id);

-- Enable Row Level Security
ALTER TABLE usage_data ENABLE ROW LEVEL SECURITY;

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.

Setup

cd claude-telemetry/agent
python3 -m venv venv

# Linux/macOS
source venv/bin/activate

# Windows
.\venv\Scripts\Activate

pip install -e .

Configure

Run the interactive setup:

claude-tracker setup

This will prompt you for:

• Supabase URL — your project URL
• Supabase API Key — the agent's API key
• Machine name — a friendly name for this PC (e.g., "work-laptop")

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

Non-interactive setup

You can also run claude-tracker setup --non-interactive with environment variables for automated deployments.

First Sync

Test the connection with a manual sync:

claude-tracker sync --verbose

You should see output confirming how many sessions were synced.

Install as Service

Set up automatic background syncing:

claude-tracker install-service

This creates a system service that syncs every 15 minutes. See Agent Setup for OS-specific details.

Verify

Check that the agent is running:

claude-tracker service-status

Then open your dashboard — you should see data appearing.

Troubleshooting

Agent can't connect to Supabase

• Verify your Supabase URL and API key in ~/.claude-tracker/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 claude-tracker sync --verbose for detailed output
• Verify Claude Code has been used on this machine (check ~/.claude/projects/)
• Run claude-tracker local --daily to inspect local data without syncing

Service won't start

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