Agent Setup

The claude-telemetry agent is a lightweight Python daemon that calls ccusage to extract usage data from Claude Code's logs and syncs it to your Supabase database. The agent does no custom JSONL parsing — it delegates that to ccusage and focuses only on multi-PC aggregation and centralized sync.

How It Works

1. The agent calls ccusage to extract session data from Claude Code's log files
2. ccusage handles all JSONL parsing and pricing calculation
3. The agent tags data with a unique machine ID and pushes it to Supabase
4. A unique machine ID is generated on first run to identify this PC

Commands

Command	Description
claude-tracker setup	Interactive first-time configuration
claude-tracker setup --non-interactive	Non-interactive setup (uses env vars)
claude-tracker sync	Manual one-time sync
claude-tracker sync --verbose	Sync with detailed output
claude-tracker sync --force	Re-sync all data
claude-tracker daemon	Run continuous sync in the foreground
claude-tracker daemon --interval 10	Custom interval in minutes
claude-tracker install-service	Install as a background system service
claude-tracker uninstall-service	Remove the background service
claude-tracker service-status	Check daemon status
claude-tracker status	Show config and last sync
claude-tracker local --daily	View local data without syncing
claude-tracker uninstall	Remove agent config from this machine

See the full CLI Reference for details on each command.

Installation by OS

Linux (systemd)

claude-tracker install-service

This creates a systemd user service at ~/.config/systemd/user/claude-tracker.service.

Manage the service:

systemctl --user status claude-tracker
systemctl --user restart claude-tracker
journalctl --user -u claude-tracker -f  # live logs

macOS (launchd)

claude-tracker 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)

claude-tracker install-service

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

• Runs at user logon
• Repeats every 15 minutes indefinitely
• 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-tracker/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": 15,
  "log_directory": "~/.claude/projects",
  "last_sync": "2026-04-04T12: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	15	How often to sync in daemon mode
log_directory	~/.claude/projects	Where Claude Code stores log files

Updating the Agent

To update to the latest version:

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