claude-telemetry

Appearance

Changelog ​

All notable changes to claude-telemetry are documented here. This project follows Semantic Versioning.

v0.3.1 (2026-04-09) ​

Bug Fix ​

  • setup-statusline fix — cc-telemetry setup-statusline was corrupting ~/.claude/settings.json in some configurations. Fixed JSON merging logic.

v0.3.0 (2026-04-08) ​

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. pip install cc-telemetry is now the recommended install method.

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

Real-time data capture via hooks

  • SessionEnd + Stop hooks replace 15-minute polling — data syncs the moment a session ends
  • Detached process pattern — sub-100ms hook execution, zero blocking
  • 2-minute debounce on Stop hook to avoid spam
  • Polling daemon kept as 60-minute backup for reconciliation
  • New command: cc-telemetry setup-hooks
  • Special thanks to @mikeadolan (claude-brain) for the architecture

MCP Server with 12 tools

  • 7 data tools: get_daily_usage, get_weekly_usage, get_active_blocks, get_rate_limits, get_machines, get_projects, get_plan_savings
  • 5 analytics tools: compare_periods, get_trends, detect_anomalies, compare_projects, get_cost_forecast
  • FastMCP with stdio transport — works in Claude Code CLI and VS Code extension
  • New command: cc-telemetry setup-mcp

Insights Engine in the dashboard

  • Trend Card — UP/DOWN/STABLE direction with daily slope and first/second half comparison
  • Daily Cost Chart with red dots on anomalous days (z-score >2) and dashed 7-day forecast line
  • Week-over-Week comparison with top 3 project movers
  • 7-Day Forecast with low/high confidence range and sparkline
  • Anomalies Detected table sorted by z-score deviation
  • MCP hint footer with copy-to-clipboard examples
  • Period selector: 7d / 30d / 90d

Webhook notifications (Discord/Slack)

  • Auto-detection of Discord vs Slack webhook URLs
  • Project budget alert at 90% threshold
  • Rate limit alert (5h or weekly) at 90% threshold
  • Anti-spam: maximum one alert per type per day
  • Configure in Settings → Notifications

Unified setup wizard

  • cc-telemetry setup is now a complete interactive wizard
  • Checks and installs ccusage/ccost dependencies
  • Configures statusline, hooks, MCP server, and daemon
  • Runs initial sync and shows summary
  • --minimal flag for base config only

cc-telemetry doctor

  • 10-point health check: ccusage, ccost, config, Supabase, statusline, hooks, MCP, daemon, last sync, hook activity
  • Each failed check includes an actionable fix hint

PyPI publishing

  • pip install cc-telemetry — no more git clone required
  • GitHub Actions trusted publishing (no API tokens)

UX Improvements ​

  • Empty states with SVG illustrations across Overview, Daily, Blocks, Projects, Sessions, and Insights
  • Deploy page simplified from 6 steps to 3
  • Multi-machine Active Block card shows all active blocks side-by-side
  • Machine status consistency: Online <15min, Idle <24h, Offline >24h
  • Last Activity timestamps show full datetime instead of date only

Bug Fixes ​

  • Blocks page TIMESTAMPTZ filter excluded blocks from the current day
  • Machine status used DATE instead of TIMESTAMPTZ — all machines showed Offline
  • Stale active blocks never deactivated when ccusage reported them as completed
  • Global 401 handling — inconsistent token clearing centralized in API client
  • Division by zero crash in Insights when no recent data
  • Daemon logging silent crash with pythonw.exe on Windows
  • 11+ silent except: pass patterns replaced with proper logging

Refactors ​

  • Naming unification: claude-tracker → cc-telemetry (CLI and PyPI package)
  • Auto-migration on first run: config directory, hook scripts, MCP entries, statusline commands
  • Rotating log files with 10 MB max per file and 5 backups

Migration from v0.2.0 ​

From source install:

bash
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

Or fresh install from PyPI:

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

Known Issues ​

  • Project Budgets shows all 30+ projects in a long list — needs search/filter
  • Hooks may not fire consistently in VS Code Claude Code sessions (CLI works as expected)
  • get_weekly_usage MCP tool does not yet return the current week
  • Models page shows "0001%" instead of "100%" on the y-axis

v0.2.0 (2026-04-06) ​

Analytics & Rate Limits ​

  • Plan vs API Cost — Compare subscription cost against API-equivalent pricing (Pro/Max5x/Max20x)
  • Weekly Reports — Daily/Weekly toggle with stacked bar charts, aligned with rate limit windows
  • 5-Hour Blocks — Multi-PC block timeline with active block card, burn rate, and overlap detection
  • 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

v0.1.0 (2026-04-04) ​

Initial Release ​

Agent

  • Python sync agent with JSONL log parsing via ccusage
  • Interactive setup command for first-time configuration
  • sync command for manual one-time data push
  • daemon command for continuous background syncing
  • install-service / uninstall-service for OS-native service management
  • status command for agent health checks
  • Support for Linux (systemd), macOS (launchd), and Windows (Task Scheduler)
  • Automatic machine ID generation (UUID)
  • Configurable sync interval (default: 15 minutes)
  • Offline resilient — retries on next interval if network is unavailable

Dashboard

  • React web application deployed to Cloudflare Pages
  • 9 dashboard pages:
    • Overview — total cost, daily chart, model pie, machine cards
    • Daily — stacked area chart, top 10 days, hour heatmap
    • Projects — cost by project, pie distribution, full table
    • Models — Opus/Sonnet/Haiku breakdown, mix over time, savings alert
    • Machines — per-machine cards, comparison chart, status badges
    • Deploy — generate agent install commands with one-click copy
    • Sessions — paginated table with sorting and filters
    • Insights — rate projections, optimization tips, trend analysis
    • Settings — machine management, export, alert thresholds
  • Dark mode UI
  • Machine-level filtering on all pages
  • CSV and JSON export
  • Responsive design (mobile, tablet, desktop)

Infrastructure

  • Cloudflare Worker proxy — zero API keys in frontend
  • Supabase Auth with magic link authentication
  • Email whitelist for access control
  • Row-Level Security on all database tables
  • Supabase PostgreSQL with optimized indexes

Data

  • ccusage integration for Claude Code JSONL log parsing
  • Token tracking: input, output, cache read, cache write
  • Cost calculation using Anthropic's published API pricing
  • Session metadata: model, timestamps, duration, project path

Released under the MIT License.

Copyright © 2025 Ryan Barbosa