Agent Setup

The claude-telemetry agent is a lightweight Python tool that calls ccusage to extract usage data from Claude Code's logs and syncs it to your Supabase database. Since v0.3.0, data syncs in real-time via Claude Code hooks — the polling daemon is kept as a 60-minute backup.

How It Works

1. Real-time (primary): Claude Code hooks (SessionEnd + Stop) trigger a sync the moment a session ends — sub-100ms execution via a detached process
2. Polling (backup): The daemon syncs every 60 minutes to catch anything hooks might miss
3. The agent calls ccusage to extract session data — no custom JSONL parsing
4. Data is tagged with a unique machine ID and pushed to Supabase

Commands

Command	Description
cc-telemetry setup	Interactive setup wizard (configures everything)
cc-telemetry setup --minimal	Base config only (no hooks/MCP/statusline)
cc-telemetry setup --non-interactive	Non-interactive setup (uses env vars)
cc-telemetry sync	Manual one-time sync
cc-telemetry sync --verbose	Sync with detailed output
cc-telemetry sync --force	Re-sync all data
cc-telemetry daemon	Run continuous sync in the foreground
cc-telemetry daemon --interval 10	Custom interval in minutes
cc-telemetry install-service	Install as a background system service
cc-telemetry uninstall-service	Remove the background service
cc-telemetry service-status	Check daemon status
cc-telemetry status	Show config and last sync
cc-telemetry local --daily	View local data without syncing
cc-telemetry setup-hooks	Configure real-time Claude Code hooks
cc-telemetry setup-mcp	Configure MCP server for natural language queries
cc-telemetry setup-statusline	Configure rate limit tracking in statusline
cc-telemetry doctor	Run 10-point health check
cc-telemetry uninstall	Remove agent config from this machine

See the full CLI Reference for details on each command.

Installation by OS

Linux (systemd)

cc-telemetry install-service

This creates a systemd user service at ~/.config/systemd/user/cc-telemetry.service.

Manage the service:

systemctl --user status cc-telemetry
systemctl --user restart cc-telemetry
journalctl --user -u cc-telemetry -f  # live logs

macOS (launchd)

cc-telemetry install-service

This creates a launchd plist at ~/Library/LaunchAgents/com.claude-telemetry.agent.plist.

Manage the service:

launchctl list | grep claude-telemetry
launchctl stop com.claude-telemetry.agent
launchctl start com.claude-telemetry.agent

Windows (Task Scheduler)

cc-telemetry install-service

This creates a scheduled task named claude-telemetry-agent that:

• Runs at user logon
• Repeats every 60 minutes (backup for hooks)
• Runs in the background (no console window)

Manage the task:

# Check status
schtasks /query /tn "claude-telemetry-agent"

# Run immediately
schtasks /run /tn "claude-telemetry-agent"

# Delete
schtasks /delete /tn "claude-telemetry-agent" /f

Configuration

The agent stores its configuration at ~/.claude-telemetry/config.json:

{
  "supabase_url": "https://your-project.supabase.co",
  "supabase_key": "your-agent-api-key",
  "machine_name": "work-laptop",
  "machine_id": "auto-generated-uuid",
  "sync_interval_minutes": 60,
  "log_directory": "~/.claude/projects",
  "last_sync": "2026-04-08T12:00:00Z"
}

Field	Default	Description
supabase_url	—	Your Supabase project URL
supabase_key	—	Agent API key
machine_name	hostname	Friendly name for this PC
machine_id	auto	UUID generated on first run
sync_interval_minutes	60	How often to sync in daemon mode (backup for hooks)
log_directory	~/.claude/projects	Where Claude Code stores log files

Updating the Agent

From PyPI (recommended)

pip install --upgrade cc-telemetry
cc-telemetry doctor

From source

cd claude-telemetry/agent
git pull
pip install -e . --upgrade
cc-telemetry uninstall-service
cc-telemetry install-service