claude-code-stats 0.1.1

Usage analytics for Claude Code CLI

Claude Code Stats

Usage analytics for Claude Code CLI - see how much time you actually spend using Claude Code.

Features

• Active Time Tracking: Estimates actual usage time by analyzing gaps between messages (accounts for idle periods, breaks, and sessions left open overnight)
• Session Analytics: Track session counts, message breakdowns, and efficiency metrics
• HTML Stats Cards: Generate shareable cards for Reddit, social media, or your website (dark and light themes)
• Token Usage: Track input/output tokens per day with message and token ratios
• Command Usage: Monitor /clear and /compact command frequency
• Model Statistics: View token usage by model from Claude Code's cache
• Hourly Distribution: See when you're most active with Claude Code

Installation

Quick Start (No Installation)

# Clone and run directly
git clone https://github.com/joshroman/claude-code-stats.git
cd claude-code-stats
python3 claude_code_stats.py

Install as Package

pip install claude-code-stats

Or install from source:

git clone https://github.com/joshroman/claude-code-stats.git
cd claude-code-stats
pip install .

Usage

# Print markdown report to terminal
claude-code-stats

# Save report to file
claude-code-stats -o report.md

# Generate shareable HTML card (compact)
claude-code-stats --html card -o stats.html

# Generate full HTML stats card with chart
claude-code-stats --html full -o stats.html

# Specify time period (7, 30, or 90 days)
claude-code-stats --html full --period 30 -o stats.html

# Include token usage in markdown report
claude-code-stats --tokens

# Custom idle threshold (default: 15 minutes)
claude-code-stats --gap-threshold 10

# Quiet mode (no progress messages)
claude-code-stats -q -o report.md

# Light mode (Anthropic brand colors)
claude-code-stats --html full --light -o stats.html

# Add GitHub username to card
claude-code-stats --html full --username @yourname -o stats.html

Options

Option	Description
-o, --output FILE	Save report to file (default: print to stdout)
--html card|full	Generate HTML output: card for compact, full for detailed with chart
-p, --period 7|30|90	Time period for HTML output (default: 7 days)
-t, --tokens	Include token usage columns in markdown daily breakdown
-g, --gap-threshold MINS	Minutes of inactivity before counting as idle (default: 15)
--light	Use light theme with Anthropic brand colors
-u, --username NAME	GitHub username to display on HTML cards (or set GITHUB_USERNAME in .env)
-q, --quiet	Suppress progress messages
-V, --version	Show version number

Sample Output

# Claude Code Usage Report

Generated: **2025-12-31 10:59**

## Summary

| Period | Sessions | Messages | Active Time | Wall-Clock | Efficiency |
|--------|----------|----------|-------------|------------|------------|
| Last 7 days | 273 | 35938 | **68.4h** | 453.6h | 15% |
| Last 30 days | 871 | 99885 | **191.9h** | 2370.9h | 8% |

## Last 7 Days - Daily Breakdown

| Date | Sessions | Active | Clock | User Msgs | Claude Msgs | Clears | Compacts |
|------|----------|--------|-------|-----------|-------------|--------|----------|
| 2025-12-31 | 22 | 9.4h | 21.2h | 260 | 3026 | 31 | 42 |
| 2025-12-30 | 34 | 11.9h | 2.5d | 306 | 3251 | 6 | 63 |
...

How It Works

Data Sources

Claude Code stores conversation data in ~/.claude/:

• projects/**/*.jsonl - Conversation transcripts with timestamps
• __store.db - SQLite database with response timing data
• stats-cache.json - Pre-computed usage statistics

Methodology

Active Time is calculated by:

1. Loading all message timestamps from conversation files
2. Calculating gaps between consecutive messages
3. Summing gaps that are ≤ threshold (default: 15 minutes)
4. Longer gaps indicate idle time (bathroom breaks, meetings, left overnight)

This prevents inflated numbers from sessions that were left open but not actively used.

Metrics Explained

Metric	Description
Active Time	Estimated actual usage (gaps ≤ threshold)
Wall-Clock Time	Total time from first to last message (includes idle)
User Prompts	Actual human messages (excludes tool results and system messages)
Claude Msgs	Number of Claude assistant responses
Tool Results	Tool/function call results returned to Claude
Message Ratio	Claude messages ÷ User prompts (how much Claude responds per prompt)
Token Ratio	Output tokens ÷ Input tokens
Clears	Number of /clear commands used
Compacts	Number of /compact commands + auto-compactions

Requirements

• Python 3.8+
• Claude Code installed and used at least once

No external dependencies required - uses only Python standard library.

Privacy

This tool only reads data from your local ~/.claude/ directory. No data is sent anywhere - all processing happens locally on your machine.

Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

License

MIT License - see LICENSE for details.

Related

• Claude Code - Anthropic's official CLI for Claude
• Claude Code Documentation