Claude Analytics 🚀 - Advanced Claude Code Analytics

✨ What's New in This Enhanced Version

This fork adds comprehensive token tracking and analytics that the original version was missing:

• 💰 Real API Cost Analysis - See exactly how much you save with Claude Max vs pay-per-token pricing
• 🔥 Token Usage Heatmaps - Discover your peak productivity hours with visual analytics
• 📅 Project Timeline Visualization - Track session duration and parallel work patterns
• 📊 Advanced Export System - Export data to CSV/JSON for external analysis
• 🎯 Enhanced Statistics - Detailed breakdowns of input/output/cache token usage
• ⚡ Real-time Tracking - Live token snapshots every 5 minutes

🚀 Quick Start

# Install globally
npm install -g claude-analytics

# Initialize automatic logging
claude-analytics init

# Start logging in any terminal
claude-analytics start

# View enhanced statistics
claude-analytics stats

📊 Features Overview

💰 API Cost Analysis

Understand exactly how much your Claude Max subscription saves you:

$ claude-analytics stats

📈 Statistics:
Active sessions: 30

🎯 Token Usage:
Input tokens: 31,154
Output tokens: 6,181
Cache creation tokens: 60,571
Cache read tokens: 706,100
Total tokens: 804,006

💰 Cost Analysis:
Claude Max subscription: $200/month
Cost per session: $6.67

🚨 API Cost Comparison (if using pay-per-token):
Claude 4 Opus:    $3.13 (1.6% of subscription)
Claude 4 Sonnet:  $0.63 (0.3% of subscription)
Claude 3.5 Haiku: $0.17 (0.1% of subscription)

💎 Subscription savings: $196.87 (98.4% saved vs most expensive API)

🔥 Token Usage Heatmaps

Find your most productive hours with visual token usage patterns:

$ claude-analytics heatmap

📊 Hourly Token Usage Pattern:
00:00 │░░░░░░░░░░░░░░░░░░░░│ 0 tokens
01:00 │░░░░░░░░░░░░░░░░░░░░│ 0 tokens
02:00 │░░░░░░░░░░░░░░░░░░░░│ 0 tokens
...
08:00 │█████████████░░░░░░░│ 1,608,012 tokens
09:00 │████████████████████│ 2,412,018 tokens
10:00 │░░░░░░░░░░░░░░░░░░░░│ 0 tokens
...

🎯 Peak Usage Analysis:
Peak hour: 09:00 (2,412,018 tokens)
Quietest hour: 08:00

⏰ Time Period Analysis:
Morning (06-12): 4,020,030 tokens
Afternoon (12-18): 0 tokens
Evening (18-24): 0 tokens
Night (00-06): 0 tokens

📅 Project Timeline Visualization

Track your session patterns and parallel work efficiency:

$ claude-analytics timeline

🕐 Session Timeline (Recent):
🔴 13:39 - 15:09 (1h 30m) | Session: ...64164
🔴 13:47 - 13:47 (0m) | Session: ...94153
🟢 13:47 - ongoing (active) | Session: ...95227
🟢 13:49 - ongoing (active) | Session: ...96635
🟢 14:01 - ongoing (active) | Session: ...55296
🔴 14:50 - 15:12 (22m) | Session: ...90815

📊 Summary:
Total sessions tracked: 30
Currently active: 15
Completed today: 15

📊 Data Export

Export your productivity data for external analysis:

# Export to CSV
$ claude-analytics export csv
📊 Exporting data in CSV format...
✅ CSV export saved: ~/Documents/claude-logs/claude-analytics-export-2025-05-29.csv

# Export to JSON
$ claude-analytics export json
📊 Exporting data in JSON format...
✅ JSON export saved: ~/Documents/claude-logs/claude-analytics-export-2025-05-29.json

📈 Export Summary:
Sessions exported: 30
Active sessions: 15
Total tokens: 4,020,030

🛠️ Installation & Setup

Option 1: Global Install (Recommended)

npm install -g claude-analytics
claude-analytics init

Option 2: Manual Setup

git clone https://github.com/sooth/claude-analytics.git
cd claude-analytics
npm install -g .
claude-analytics init

The init command will:

• Set up automatic logging for all terminals
• Configure 5-minute token snapshots and 15-minute log merging
• Create session tracking directories
• Add shell integration to your .zshrc

🎯 Usage

Basic Commands

# View comprehensive statistics
claude-analytics stats

# Real-time dashboard
claude-analytics dashboard

# Generate usage heatmaps
claude-analytics heatmap

# View session timeline
claude-analytics timeline

# Export data
claude-analytics export csv    # or json

# Merge session logs
claude-analytics merge

Starting Sessions

After running claude-analytics init, you have two options:

1. Use the wrapper (automatic):

   claude-logged  # Instead of 'claude'

2. Manual activation per terminal:

   claude-analytics start  # Then follow instructions

💡 Understanding Your Data

Token Types Explained

• Input tokens: Text you send to Claude
• Output tokens: Claude's responses
• Cache creation tokens: Building prompt cache (90% discount available)
• Cache read tokens: Reading from prompt cache (huge savings)

Important: Token numbers show cumulative project totals, not per-session usage. This is how Claude Code tracks usage - by project, not individual sessions. All sessions in the same project will show the same total numbers.

Cost Savings Analysis

The cost comparison shows how much you would pay with different Claude API tiers:

• Claude 4 Opus: Premium model ($15/$75 per million tokens)
• Claude 4 Sonnet: Balanced model ($3/$15 per million tokens)
• Claude 3.5 Haiku: Fast model ($0.80/$4 per million tokens)

Your Claude Max subscription provides unlimited usage for $200/month, typically saving 95%+ vs API pricing.

Productivity Insights

• Heatmaps reveal your most productive hours
• Timeline shows session overlap and parallel efficiency
• Export data enables custom analysis in Excel, Python, etc.

🖥️ Platform Support

• ✅ macOS
• ✅ Linux
• ✅ Windows (WSL)

📁 File Structure

Your logs are organized in ~/Documents/claude-logs/:

claude-logs/
├── 2025-05-29.md              # Daily merged logs
├── sessions/                  # Individual session logs
│   ├── 1748366389-48238.log   # Session-specific tracking
│   └── 1748366671-51644.log
└── claude-logger-export-*.csv # Exported data files

🚨 Troubleshooting

Sessions not logging?

1. Restart your terminal after running claude-analytics init
2. Check that ~/Documents/claude-logs/sessions/ exists
3. Try claude-analytics start in each terminal

Token data not showing?

1. Ensure you're using Claude Code (not Claude web interface)
2. Check that ~/.claude.json exists and contains project data
3. Run a few Claude commands to generate token usage

Export files empty?

1. Wait for token snapshots to be generated (every 5 minutes)
2. Use claude-logged wrapper or manual claude-analytics start
3. Check session logs in ~/Documents/claude-logs/sessions/

🤝 Contributing

This is an enhanced fork of the original claude-logger, now published as claude-analytics. Contributions welcome!

1. Fork this repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

📝 License

MIT License - see LICENSE file for details.

🙏 Credits

• Original claude-logger by @daiokawa
• Enhanced with comprehensive analytics and token tracking
• Built for the Claude Code power user community

Track smarter. Code better. Optimize everything.