📊 Command Usage Analytics System

This release introduces comprehensive tracking of CLI command executions to understand community usage patterns.

✨ What's New

Command Usage Tracking

• Track execution of major CLI commands (--chats, --analytics, --health-check, --plugins, --sandbox, etc.)
• Store analytics in Neon PostgreSQL database with auto-aggregated statistics
• Fire-and-forget tracking (non-blocking, respects user privacy)
• Includes metadata: tunnel usage, platform, Node version, session IDs

Database & Analytics

• New Neon database tables: command_usage_logs, command_usage_stats
• Auto-updating statistics via PostgreSQL triggers
• Useful views: daily usage, platform distribution, popular commands (30 days)
• Independent from component download tracking (Supabase)

API Endpoint

• New endpoint: /api/track-command-usage
• Validates command names against whitelist
• Handles metadata as JSONB for flexible analytics
• CORS-enabled for cross-origin requests

🧪 Testing

Comprehensive Test Suite

• ✅ 18/18 tests passing
• Added 6 new tests for command tracking endpoint
• Validates all 11 supported commands
• Tests metadata handling, validation, error cases
• Response time checks (<30s for all endpoints)

🔒 Privacy & Security

• Respects Privacy: Users can opt-out with CCT_NO_TRACKING=true
• No Secrets: All sensitive data uses environment variables
• Anonymous: No personally identifiable information collected
• Non-blocking: Tracking failures never impact CLI functionality

📦 What's Tracked

Commands tracked for community analytics:

• --chats (with tunnel metadata)
• --analytics (with tunnel metadata)
• --health-check
• --plugins
• --sandbox (with provider and prompt metadata)
• --agents (with tunnel metadata)
• --chats-mobile (with tunnel metadata)
• command-stats, hook-stats, mcp-stats

🔧 Technical Details

Database Architecture

• Platform: Neon PostgreSQL (serverless)
• Auto-scaling with connection pooling
• Automatic stats aggregation via triggers
• Efficient indexing for fast queries

Files Changed

• api/track-command-usage.js - New API endpoint
• database/migrations/002_create_command_usage_logs.sql - Database schema
• cli-tool/src/tracking-service.js - Added trackCommandExecution()
• cli-tool/src/index.js - Integrated tracking for 10+ commands
• api/__tests__/endpoints.test.js - Added comprehensive tests

📊 Analytics Queries

View command usage:
```sql
SELECT command_name, total_executions, unique_sessions
FROM command_usage_stats
ORDER BY total_executions DESC;
```

View daily trends:
```sql
SELECT * FROM daily_command_usage
ORDER BY date DESC;
```

🚀 Installation

```bash
npx claude-code-templates@latest

Or install globally

npm install -g claude-code-templates@1.26.4
```

🌐 Links

• Website
• Documentation
• NPM Package
• GitHub

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com