Agent CLI Reference

The claude-telemetry agent is a Python command-line tool that calls ccusage to extract usage data from Claude Code's logs and syncs it to Supabase.

Usage

claude-tracker <command> [options]

Commands

setup

Interactive first-time configuration. Prompts for Supabase credentials and machine name.

claude-tracker setup

Prompts:

• Supabase URL
• Supabase API Key
• Machine name (defaults to system hostname)

Output: Creates ~/.claude-tracker/config.json with a new machine UUID.

For automated deployments, use the non-interactive mode:

claude-tracker setup --non-interactive

This reads configuration from environment variables instead of prompting.

---

sync

Perform a one-time sync of new sessions since the last sync.

claude-tracker sync [--verbose] [--force]

Flag	Description
--verbose	Show detailed output for each synced session
--force	Re-sync all data, not just new sessions since last sync

Example output:

Syncing usage data...
Found 12 new sessions since 2026-04-04T10:30:00Z
Synced 12 sessions (3,450 input tokens, 8,200 output tokens)
Total cost: $0.42
Last sync updated to 2026-04-04T12:00:00Z

---

daemon

Run the agent in continuous sync mode (foreground). Syncs at the configured interval.

claude-tracker daemon [--interval N]

Flag	Description
--interval N	Custom sync interval in minutes (default: 15)

Example:

claude-tracker daemon --interval 10  # sync every 10 minutes

Press Ctrl+C to stop. For background execution, use install-service instead.

---

install-service

Install the agent as a system background service.

claude-tracker install-service

Creates the appropriate service for your OS:

• Linux: systemd user service
• macOS: launchd agent
• Windows: Task Scheduler task

See Agent Setup for OS-specific details.

---

uninstall-service

Remove the background service.

claude-tracker uninstall-service

---

service-status

Check the status of the background daemon.

claude-tracker service-status

Shows whether the service is running, stopped, or not installed.

---

status

Show the agent's current configuration and last sync time.

claude-tracker status

Example output:

claude-telemetry Agent Status
─────────────────────────
Machine:      work-laptop (a1b2c3d4-...)
Supabase:     Connected ✓
Last sync:    2026-04-04T12:00:00Z (15 minutes ago)
Service:      Running (systemd)
Config:       ~/.claude-tracker/config.json

---

local

View local usage data without syncing to Supabase.

claude-tracker local --daily

Flag	Description
--daily	Show daily usage summary from local logs

Useful for inspecting data before syncing, or when you don't have network access.

---

uninstall

Remove the agent configuration and data from this machine.

claude-tracker uninstall

This deletes ~/.claude-tracker/ and all local agent data. It does not remove data already synced to Supabase.

Statusline cleanup

If you enabled statusline tracking, also remove:

• ~/.claude/statusline.sh (Linux/macOS) or ~/.claude/statusline.ps1 (Windows)
• The statusline entry from ~/.claude/settings.json

---

setup-statusline

Configure rate limit tracking via Claude Code's statusline feature.

claude-tracker setup-statusline

Creates a statusline script that displays current rate limit usage in your terminal. The script is saved to ~/.claude/statusline.sh (Linux/macOS) or ~/.claude/statusline.ps1 (Windows) and registered in ~/.claude/settings.json.

Complete Command Reference

Command	Description
claude-tracker setup	Configure agent (interactive or --non-interactive)
claude-tracker sync	Manual sync to Supabase
claude-tracker sync --verbose	Sync with detailed output
claude-tracker sync --force	Re-sync all data
claude-tracker daemon	Run auto-sync in foreground
claude-tracker daemon --interval 10	Custom interval (minutes)
claude-tracker install-service	Install as system service
claude-tracker uninstall-service	Remove system 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 setup-statusline	Configure rate limit tracking (creates statusline script)
claude-tracker uninstall	Remove agent config from this machine

Environment Variables

Environment variables override config.json values:

Variable	Description
CC_TELEMETRY_SUPABASE_URL	Supabase project URL
CC_TELEMETRY_SUPABASE_KEY	Supabase API key
CC_TELEMETRY_MACHINE_NAME	Machine friendly name
CC_TELEMETRY_SYNC_INTERVAL	Sync interval in minutes
CC_TELEMETRY_LOG_DIR	Claude Code log directory

Config File

Location: ~/.claude-tracker/config.json

{
  "supabase_url": "https://your-project.supabase.co",
  "supabase_key": "your-api-key",
  "machine_name": "work-laptop",
  "machine_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sync_interval_minutes": 15,
  "log_directory": "~/.claude/projects",
  "last_sync": "2026-04-04T12:00:00Z"
}

Exit Codes

Code	Meaning
0	Success
1	General error
2	Configuration error (missing config, invalid credentials)
3	Network error (cannot reach Supabase)
4	Log directory not found