cc-stats 0.1.3
Visualize Claude Code usage patterns from your .claude folder
Requires Python: >=3.9
Keywords: claude, claude-code, cli, statistics, visualization

# Claude Code Stats

A visualization dashboard for your [Claude Code](https://docs.anthropic.com/en/docs/claude-code) usage patterns. Generates a static HTML dashboard from your local `.claude` folder data.

![Dashboard Demo](screenshots/dashboard.gif)

## Quick Start

```bash
pip install cc-stats
claude-stats
```

The dashboard opens automatically in your browser.

## Features

### Core Analytics
- **Activity Timeline**: Track daily messages and sessions over time
- **Date Range Filter**: Filter all charts by custom date range
- **Model Usage**: See token distribution across Sonnet, Opus, and Haiku
- **Peak Hours**: Discover when you're most productive with Claude
- **Project Breakdown**: Identify which projects get the most attention

### Cost & Efficiency
- **Cost Estimation**: Approximate API costs based on token usage
- **Cache Savings**: See how much caching saves you
- **Cache Efficiency**: Track cache hit rates

### Performance
- **Response Time**: View turn duration percentiles (p50, p95, p99)
- **API Reliability**: Track error rates and types
- **Tool Success Rate**: Monitor which tools fail most often

### Productivity
- **Task Completion**: Track todo completion rates
- **Plan Activity**: See how often you use Claude's plan mode

### Deep Dive
- **Tool Usage**: Analyze which tools (Read, Edit, Bash, etc.) you use most
- **MCP Tools**: View usage of Model Context Protocol tools and servers
- **Subagent Analysis**: Track usage of Explore, code-reviewer, Plan agents
- **Extended Thinking**: Monitor thinking token usage
- **File Edit Velocity**: Track file editing patterns
- **Conversation Depth**: Analyze conversation threading patterns

## Installation

### Option 1: PyPI (Recommended)

```bash
pip install cc-stats
```

To update:
```bash
pip install --upgrade cc-stats
```

### Option 2: From Source

```bash
git clone https://github.com/saurabharora90/claude-code-stats.git
cd claude-code-stats
pip install .
```

## Usage

```bash
# Generate dashboard from default ~/.claude folder (auto-opens browser)
claude-stats

# Specify a different .claude folder
claude-stats /path/to/.claude

# Save dashboard to a specific directory
claude-stats --output ./my-dashboard

# Generate only JSON stats (no HTML)
claude-stats --json-only --output ./stats

# Don't auto-open browser
claude-stats --no-open
```

## Options

| Option | Description |
|--------|-------------|
| `CLAUDE_FOLDER` | Path to .claude directory (default: `~/.claude`) |
| `--output, -o` | Output directory for dashboard (default: temp directory) |
| `--open/--no-open` | Auto-open browser after generation (default: `--open`) |
| `--json-only` | Only export stats.json, skip HTML dashboard |

## Requirements

- Python 3.9+
- `click` (installed automatically with pip)

## Privacy

All data processing happens locally. No data is sent anywhere. The generated dashboard is a static HTML file that works completely offline.

## Documentation

- [Metrics Documentation](METRICS.md) - Detailed explanation of all metrics and charts

## Data Sources

The tool reads from these files in your `.claude` folder:

| File | Data Extracted |
|------|----------------|
| `stats-cache.json` | Daily activity, model tokens, session totals, peak hours |
| `projects/*/sessions-index.json` | Per-project session counts and summaries |
| `projects/*/*.jsonl` | Tool calls, turn durations, API errors, thinking blocks |
| `todos/*.json` | Task completion statistics |
| `plans/*.md` | Plan activity |
| `file-history/` | File edit patterns |
| `settings.json` | Enabled plugins |
| `history.jsonl` | Slash command usage |

## Contributing

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

## License

MIT License. See [LICENSE](LICENSE) for details.