Claude Analytics 🚀 - Advanced Claude Code Analytics

🔥 Track ALL your Claude sessions with advanced analytics and cost insights 🔥

✨ 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

``bash


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

$3

Understand exactly how much your Claude Max subscription saves you:

`bash
$ 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)
`

$3

Find your most productive hours with visual token usage patterns:

`bash
$ 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
`

$3

Track your session patterns and parallel work efficiency:

`bash
$ 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
`

$3

Export your productivity data for external analysis:

`bash


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

$3


`bash
npm install -g claude-analytics
claude-analytics init
`

$3

`bash
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

$3

`bash


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
`

$3

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

1. Use the wrapper (automatic):
`bash
claude-logged # Instead of 'claude'
`

2. Manual activation per terminal:
`bash
claude-analytics start # Then follow instructions
`

💡 Understanding Your Data

$3

- 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.

$3

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.

$3

- 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

$3


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

$3

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

$3

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.