v0.3.1 — Fix setup-statusline

Critical fix for setup-statusline

Patch release fixing a critical bug in cc-telemetry setup-statusline that corrupted ~/.claude/settings.json.

Bug

_setup_statusline_internal() was writing StatusLine as a key inside the hooks dict instead of statusLine as a top-level key. This caused Claude Code to reject the entire settings file with:

Settings file failed to parse: ~/.claude/settings.json — Invalid key in record. Permission rules and other settings from this file are not in effect.

Anyone who ran cc-telemetry setup or cc-telemetry setup-statusline on v0.3.0 was affected.

Fix

• setup-statusline now writes statusLine correctly at the top level of settings.json with the proper {type, command, padding} format.
• Auto-migration runs on first command after upgrade — if your settings.json has the broken hooks.StatusLine entry, it's automatically migrated to the correct location.
• cc-telemetry doctor updated to check the correct top-level location.

Upgrade

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

The migration runs automatically. No manual intervention needed.

If you previously had to manually fix your settings.json, it will continue working — the migration is idempotent.

Full Changelog: v0.3.0...v0.3.1

v0.3.0 — Real-time, Analytics & PyPI

This release transforms claude-telemetry from a polling-based tracker into a real-time analytics platform with deep Claude Code integration. It also marks our first PyPI release: pip install cc-telemetry is now the recommended install method.

Note on naming: The PyPI package and CLI command are now cc-telemetry. The project, repository, and documentation site keep the claude-telemetry name. This change was needed because claude-telemetry was already taken on PyPI. An automatic migration handles existing installations on first run.

---

Highlights

Real-time data capture via hooks

No more 15-minute delays. Data syncs to your dashboard the moment your Claude Code session ends, using the new SessionEnd and Stop hooks.

• New command: cc-telemetry setup-hooks
• Detached process pattern — sub-100ms hook execution, zero blocking
• 2-minute debounce on Stop hook to avoid spam
• Polling daemon kept as a 60-minute backup for reconciliation

Special thanks to @mikeadolan (claude-brain) for the architecture insights and the detached process pattern.

MCP Server with 12 tools

Ask Claude about your usage in natural language. Configure once with cc-telemetry setup-mcp and start asking:

• "How much did I spend this week across all my machines?"
• "What's my most expensive project?"
• "Compare my usage this week vs last week"
• "Are there any anomalies in my spending this month?"
• "What's my forecast for the next 7 days?"

Data tools (7):
get_daily_usage, get_weekly_usage, get_active_blocks, get_rate_limits, get_machines, get_projects, get_plan_savings

Analytics tools (5) — new!

• compare_periods — compare two time periods with cost diff, token diff, and top movers
• get_trends — linear regression with direction detection and 7-day projection
• detect_anomalies — z-score based anomaly detection (configurable threshold)
• compare_projects — side-by-side project comparison
• get_cost_forecast — moving average forecast with confidence range

The MCP server uses FastMCP with stdio transport and works in the Claude Code CLI as well as the VS Code extension.

Insights Engine in the dashboard

The Insights page has been completely rewritten with a new analytics engine. Everything that the MCP tools can analyze is now visible directly in the dashboard:

• Trend Card — UP/DOWN/STABLE direction, daily slope, first half vs second half comparison
• Daily Cost Chart with anomalies and forecast — area chart with red dots on anomalous days (z-score >2) and a dashed forecast line for the next 7 days
• Week-over-Week comparison — last week vs this week with top 3 project movers
• 7-Day Forecast — predicted cost with low/high confidence range and sparkline
• Anomalies Detected table — days with z-score >2, sorted by deviation
• MCP hint footer — copy-to-clipboard examples for asking Claude deeper questions
• Period selector: 7d / 30d / 90d

Two new Worker endpoints power the dashboard analytics: /api/analytics-trends and /api/analytics-compare-periods.

Webhook notifications

Get notified on Discord, Slack, or any webhook when something needs attention:

• A project hits 90% of its monthly budget
• Rate limit (5h or weekly) exceeds 90%

Configure in Settings → Notifications. Discord and Slack are auto-detected and receive properly formatted embeds/blocks. Anti-spam: maximum one alert per type per day.

The cron endpoint (POST /api/cron-check-notifications) is protected by CRON_SECRET and runs every 15 minutes via Cloudflare Pages cron triggers.

Unified setup wizard

The cc-telemetry setup command is now a complete interactive wizard:

1. Checks Node.js, ccusage, and ccost (offers to install missing dependencies)
2. Prompts for Supabase URL, service key, and machine name
3. Asks "Configure everything automatically?" (default yes)
4. Configures statusline, hooks, MCP server, and installs the daemon
5. Runs an initial sync to populate the dashboard immediately
6. Reports a summary with the dashboard URL

New flag: --minimal for users who want only the base config without extras. The existing --non-interactive flag now does full setup by default.

cc-telemetry doctor — health check command

Diagnose your installation in one command:

Claude Telemetry — Health Check

  ccusage installed      ✓ available via npx
  ccost installed        ✓ 0.3.1
  Config valid           ✓ machine: Desktop-Casa
  Supabase reachable     ✓ connected
  Statusline configured  ✓
  Hooks configured       ✓ SessionEnd + Stop
  MCP server registered  ✓
  Daemon running         ✓ PID 12345
  Last sync              ✓ 2 minutes ago
  Hook sync active       ✓ 12 minutes ago

  10/10 checks passed

Each failed check returns an actionable hint to fix it.

PyPI publishing

cc-telemetry is now on PyPI:

pip install cc-telemetry
cc-telemetry setup

The release pipeline uses GitHub Actions trusted publishing (no API tokens). Every GitHub release published from now on will trigger an automatic PyPI publish.

---

UX improvements

• Empty states — six new SVG illustrations and friendly messages across Overview, Daily, Blocks, Projects, Sessions, and Insights pages for users without data yet
• Simplified Deploy page — install steps reduced from 6 to 3 (npm install -g ccusage ccost → pip install cc-telemetry → cc-telemetry setup)
• Multi-machine Active Block card — when "All Machines" is selected, the Blocks page now shows all active blocks side-by-side with machine labels, instead of arbitrarily picking one
• Machine status consistency — Machines page and Settings page now use the same status logic (Online <15min, Idle <24h, Offline >24h)
• Last Activity timestamps — Machines page now shows full YYYY-MM-DD HH:MM:SS instead of date only

---

Bug fixes

• Blocks page TIMESTAMPTZ filter — the date filter cast 2026-04-08 to midnight UTC, excluding any block that started after midnight on the current day. Both the timeline and Active Block card were affected. Fixed by appending T23:59:59Z to the upper bound.
• Machine status used DATE instead of TIMESTAMPTZ — the last_activity field from get_machine_summary returned a DATE, causing all machines to be parsed as midnight UTC and always show "Offline". Fixed by fetching last_sync_at from the machines table directly.
• Stale active blocks — blocks marked is_active=true were never deactivated when ccusage reported them as completed. Sync now reconciles active flags on every run.
• Global 401 handling — token clearing logic was inconsistent across components. Centralized in the API client.
• Division by zero in Insights — page crashed when there was no recent data to compute averages.
• Daemon logging silent crash — pythonw.exe on Windows was crashing silently when stdout was unavailable. Logging now uses dedicated rotating file handlers from the start.
• Multiple silent error catches — 11+ except: pass patterns were replaced with proper logging to prevent silent failures.

---

Refactors

• Naming unification — internal Python package, config directory, and CLI references migrated from claude-tracker to claude-telemetry. PyPI package and CLI command then renamed to cc-telemetry (the claude-telemetry name was taken on PyPI). Auto-migration runs on first command and handles:
  • Config directory rename (~/.claude-tracker/ → ~/.claude-telemetry/)
  • Hook script regeneration with new paths
  • MCP entry rename in ~/.claude.json (claude-telemetry → cc-telemetry)
  • Statusline command updates in ~/.claude/settings.json
• Rotating log files — daemon, sync, and hook logs now use RotatingFileHandler with 10 MB max per file and 5 backups, preventing unbounded growth.

---

Migration from v0.2.0

If you installed v0.2.0 from source:

git pull origin main
cd agent
pip uninstall claude-usage-tracker -y
pip install -e .
cc-telemetry --version          # auto-migrates config and MCP entries
cc-telemetry setup-hooks        # regenerate hook scripts
cc-telemetry setup-mcp          # regenerate MCP config
cc-telemetry doctor             # verify everything is in order

Or, install fresh from PyPI:

npm install -g ccusage ccost
pip install cc-telemetry
cc-telemetry setup

---

Known issues

A few items did not make it into this release and are tracked for v0.3.1 / v0.4.0:

• Project Budgets settings shows all 30+ projects in a long list — needs search/filter and "show top 10 by cost" mode
• Hooks may not fire consistently in VS Code Claude Code sessions (CLI claude works as expected) — being investigated
• Daemon backup interval may not be running autonomously when hooks are configured — under investigation
• get_weekly_usage MCP tool does not yet return the current week
• Models page shows "0001%" instead of "100%" on the y-axis

---

What's next — v0.4.0

• Data retention policy (automatic aggregation of old data to keep Supabase free tier sustainable)
• Bug fix sweep from the v0.3.0 backlog
• Project Budgets UX overhaul
• Hooks reliability improvements

---

Stats

• 3 new top-level features: Real-time hooks, MCP Server (12 tools), Insights Engine
• +682 / -225 lines in the final integration commit alone (excluding earlier phase commits)
• 2 critical TIMESTAMPTZ bugs found and fixed during validation
• 10/10 doctor checks passing on final validation
• ~50 hours of focused implementation work over a single day

---

Full Changelog: v0.2.0...v0.3.0

Documentation: https://claude-telemetry.ryanbarbosa.com

Install: `pip install cc-tel...

v0.2.0 — Analytics & Rate Limits

What's New

Analytics & Rate Limits

• 5-Hour Blocks Page — Multi-PC block timeline with active block card, burn rate, and overlap detection
• Plan vs API Cost — Compare subscription cost against API-equivalent pricing (Pro/Max5x/Max20x)
• Weekly Reports — Daily/Weekly toggle with stacked bar charts
• Rate Limit Progress Bars — Visual 5-hour and weekly rate limit usage in Overview
• Usage Pace Calculator — Daily averages with trend detection (increasing/stable/decreasing)
• Project Budgets — Per-project spending limits with progress bars and alerts
• Cross-Machine Usage Pace — Combined usage metrics across all machines
• Statusline Auto-Setup — One-command rate limit tracking configuration

Improvements

• User preferences synced to Supabase (previously localStorage only)
• Agent uses pythonw.exe on Windows (no console window)
• Dashboard favicon and logo
• Fix React error #310 (hook ordering)

Migrations

Run in order after updating:

1. supabase/migrations/002_stats_extra_unique.sql
2. supabase/migrations/003_user_preferences.sql
3. supabase/migrations/004_blocks.sql

Full Changelog: v0.1.0...v0.2.0

v0.1.0 — Initial Release

claude-telemetry v0.1.0

Multi-PC Claude Code usage tracking with centralized dashboard.

Features

• Agent with auto-sync daemon (Elastic/Wazuh style)
• Dashboard: Overview, Daily, Projects, Models, Sessions, Insights, Machines, Deploy, Settings
• Supabase Auth (magic link)
• Cloudflare Workers proxy (zero exposed keys)
• Deploy page with copy-paste agent install commands
• ccusage + ccost integration
• Alert thresholds (daily/weekly cost)
• Multi-machine status tracking
• CSV/JSON export
• Error boundaries + input sanitization + batch upsert

Setup

See README

Stack

Python 3.11+ · React 18 · Vite · TailwindCSS · Recharts · Supabase · Cloudflare Pages