📊 Claude Code Monitor

Real-time telemetry monitoring and analytics for Claude Code sessions

Track token usage, monitor costs, and analyze Claude Code performance with beautiful dashboards and comprehensive analytics.

🚀 Quick Start • ✨ Features • 📊 Dashboard • 🔧 Configuration • 📈 Analytics

---

🎯 About

Claude Code Monitor is a comprehensive OpenTelemetry-based monitoring solution specifically designed to capture, store, and visualize Claude Code token usage and cost data in real-time. Whether you're a developer tracking API costs or a team analyzing AI tool usage patterns, this tool provides the insights you need.

🌟 Why Claude Code Monitor?

• 💰 Cost Transparency: Track exact token costs by model and session
• 📈 Usage Insights: Understand your Claude Code usage patterns over time
• 🔍 Real-time Monitoring: See live token consumption as you work
• 📊 Rich Analytics: Comprehensive reports and trend analysis
• 🛠 Easy Integration: Seamless OpenTelemetry integration with minimal setup
• 🎨 Beautiful Dashboards: Interactive web interface with charts and visualizations

✨ Features

🚀 Core Capabilities

• 📡 Real-time Telemetry: Receives Claude Code metrics via OTLP protocol
• 💎 Token Analytics: Track input, output, cache read/creation tokens
• 💰 Cost Tracking: Monitor spending across different AI models
• 📊 Interactive Dashboard: Beautiful web interface with real-time charts
• 📈 Prometheus Export: Industry-standard metrics for external monitoring
• 📋 Usage Reports: Daily, weekly, and historical analysis
• 🔄 Session Tracking: Monitor individual Claude Code sessions

🎨 Dashboard Features

• Real-time token distribution charts
• Per-model cost breakdown
• 30-day historical trends
• Auto-refresh every 30 seconds
• Responsive design for all devices

📊 Analytics & Reporting

• Daily usage summaries
• Weekly trend analysis
• Cost optimization insights
• Token efficiency metrics
• Session duration tracking

🚀 Quick Start

1️⃣ Install Dependencies

npm install

2️⃣ Automatic Setup (Recommended)

./setup-claude-telemetry.sh
source ~/.bashrc  # or ~/.zshrc for zsh users

3️⃣ Start Monitoring

# Start the OTLP receiver
npm run receiver

# In another terminal, start the web dashboard
npm run web

4️⃣ Use Claude Code

Use Claude Code normally - tokens will be automatically tracked! 🎉

📊 Dashboard

Access your monitoring dashboard at:

• Web Interface: http://localhost:3000
• Prometheus Metrics: http://localhost:9464/metrics

Dashboard Screenshots

┌─────────────────────────────────────────────┐
│  📊 Claude Code Usage Dashboard            │
├─────────────────────────────────────────────┤
│  Today's Stats          Token Distribution  │
│  • 1,234 Input         ████████████ 45%    │
│  • 2,567 Output        ████████████ 55%    │  
│  • 15,432 Cache Read   ████████████ 89%    │
│  • 1,098 Cache Create  ████████████ 11%    │
├─────────────────────────────────────────────┤
│  💰 Cost Breakdown     📈 30-Day Trend     │
│  • Model A: $12.34     ▲▲▲▲▲▲▲▲▲▲▲       │
│  • Model B: $5.67      ▲▲▲▲▲▲▲▲▲▲▲       │
└─────────────────────────────────────────────┘

🔧 Configuration

Manual Environment Setup

If you prefer manual configuration:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json

Environment Variables

Variable	Default	Description
CLAUDE_CODE_ENABLE_TELEMETRY	1	Enable Claude Code telemetry
OTEL_EXPORTER_OTLP_ENDPOINT	http://localhost:4318	OTLP endpoint URL
OTEL_EXPORTER_OTLP_PROTOCOL	http/json	Protocol format
OTEL_EXPORTER_PROMETHEUS_PORT	9464	Prometheus metrics port

🛠 Commands

Core Operations

npm run receiver     # 🎯 Start OTLP receiver for telemetry
npm run web         # 🌐 Launch web dashboard  
npm run monitor     # 📊 Start Prometheus metrics export

Analytics & Reports

npm run report           # 📋 Generate comprehensive usage report
npm run report daily     # 📅 Today's detailed usage
npm run report weekly    # 📈 Weekly summary and trends

Development & Testing

npm run test-data       # 🧪 Generate sample test data
npm run test-session   # 🔬 Simulate single session
npm run test-history   # 📊 Generate historical data

📈 Analytics

Usage Reports

Get detailed insights into your Claude Code usage:

$ npm run report daily

📊 Claude Code Usage Report - 2024-01-15
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💎 Token Usage:
  • Input Tokens:        1,234 (12.3%)
  • Output Tokens:       2,567 (25.7%) 
  • Cache Read:          5,432 (54.3%)
  • Cache Creation:        768 (7.7%)
  ────────────────────────────────────
  • Total Tokens:       10,001

💰 Cost Breakdown:
  • claude-3-sonnet-20241022: $12.34
  • claude-3-haiku-20240307:  $3.45
  ────────────────────────────────────
  • Total Cost:         $15.79

📈 Performance:
  • Sessions:            47
  • Avg Tokens/Session:  213
  • Peak Hour:           14:00-15:00

Prometheus Integration

Monitor your metrics with industry-standard tools:

• Grafana Dashboards: Import pre-built dashboards
• Alert Rules: Set up cost and usage alerts
• Historical Data: Long-term trend analysis

🔍 Data Storage

File Structure

ccmonitor/
├── daily-usage.json     # 💾 Primary data store
├── logs/                # 📋 Application logs
└── config/              # ⚙️ Configuration files

Data Format

Data is stored in JSON format with incremental daily aggregation:

{
  "2024-01-15": {
    "inputTokens": 1234,
    "outputTokens": 2567,
    "cacheReadTokens": 5432,
    "cacheCreationTokens": 768,
    "totalTokens": 10001,
    "sessions": 47,
    "modelCosts": {
      "claude-3-sonnet-20241022": 12.34
    }
  }
}

🚀 Advanced Usage

Remote Monitoring

Monitor Claude Code usage on remote servers:

# Create SSH tunnel
ssh -L 3000:localhost:3000 -L 9464:localhost:9464 user@server

# Access dashboards locally
open http://localhost:3000      # Web dashboard
open http://localhost:9464      # Prometheus metrics

Docker Deployment

Deploy with Docker for production environments:

# Build and run
docker build -t claude-monitor .
docker run -p 3000:3000 -p 4318:4318 -p 9464:9464 claude-monitor

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/yourusername/claude-code-monitor.git
cd claude-code-monitor
npm install
npm run dev

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

• 📖 Documentation: Check our Wiki
• 🐛 Bug Reports: Create an Issue
• 💬 Discussions: GitHub Discussions
• 📧 Email: Support Email

🌟 Acknowledgments

• OpenTelemetry for the telemetry framework
• Claude Code for the amazing AI coding assistant
• Prometheus for metrics collection
• Express.js for the web framework

---

Made with ❤️ for the Claude Code community

⭐ Star us on GitHub • 🐛 Report Bug • 💡 Request Feature