# Claude Conversation Analyzer

Aggregate, visualize, search, and estimate costs across your Claude Code conversations.

> **Do this first:** Claude Code deletes conversation history after a short period by default. Set `cleanupPeriodDays` in `~/.claude/settings.json` before you accumulate history you want to analyze:
> ```json
> { "cleanupPeriodDays": 3650 }
> ```

## What it does

- **Aggregates** Claude Code conversations from `~/.claude/projects/`
- **Estimates costs** per conversation and project using model-specific pricing
- **Visualises token progression** — cache creation, cache reads, input/output — with compaction events marked
- **Exports** to JSON (for the Next.js dashboard) or static HTML

For guidance on how to use Claude Code effectively, see [Anthropic's best practices](https://code.claude.com/docs/en/best-practices#best-practices-for-claude-code).

## Model Pricing Reference

Claude Code uses different models with varying costs per million tokens:
https://platform.claude.com/docs/en/about-claude/pricing#model-pricing

Cache read tokens are significantly cheaper than regular input tokens — the tool accounts for this when estimating costs.

## Claude Code Configuration

**Important**: To get the most value from the conversation analyzer, configure Claude Code to retain conversation history for a longer period:

```bash
# Edit your Claude Code settings (~/.claude/settings.json)
{
  "cleanupPeriodDays": 3650
}
```

By default, Claude Code may clean up conversation data after a shorter period. Setting `cleanupPeriodDays` to a large value preserves it for analysis:
- **Historical analysis**: Identify trends and patterns across months of conversations
- **Complete cost tracking**: Track cumulative API costs over time
- **Better learning**: Compare current efficiency against past conversations

The analyzer depends on conversation data stored in `~/.claude/projects/*/cache/` directories.

**Privacy note**: Conversation history includes your prompts, code, and Claude's responses — potentially sensitive content. Before setting a long retention period, consider whether that data should live indefinitely on your machine. A shorter value like 90–365 days is a reasonable middle ground if you want history without indefinite accumulation.

**Reference**: See the [Claude Code settings documentation](https://docs.claude.com/en/docs/claude-code/settings#available-settings) for all available configuration options.

## Project Structure

There are two components: a Python backend that analyzes conversations and a Next.js frontend that provides an interactive dashboard.

```
backend/                         # Python analysis engine
├── Makefile                     # All make targets
├── pyproject.toml               # Python project (uv, hatchling)
├── ruff.toml                    # Formatter/linter config
├── src/
│   ├── app.py                   # Main entry point
│   ├── analyzer.py              # Core analysis logic (scoring, costs)
│   ├── conversation_types.py    # Type definitions (dataclasses)
│   ├── cclog_loader.py          # cclog data loader with legacy fallback
│   ├── data_loader.py           # Legacy data loader (fallback)
│   ├── html_viewer.py           # Static HTML report generator
│   ├── html_viewer.js           # External JS for HTML interactivity
│   ├── json_exporter.py         # JSON/CSV export (feeds frontend)
│   ├── badge_helpers.py         # Badge generation utilities
│   ├── html_components.py       # Shared HTML components
│   └── html_styles.py           # Shared HTML/CSS styles
└── output/
    ├── analysis-data.json        # Full JSON export (used by frontend)
    ├── analysis-summary.json     # Summary statistics (optional)
    └── analysis/                 # Static HTML reports (legacy viewer)
        ├── index.html
        └── projects/<name>/index.html

frontend/                        # Next.js interactive dashboard
├── biome.json                   # Linter/formatter (Biome 2.1.2)
├── next.config.ts
├── public/data/                 # analysis-data.json (gitignored, generated)
└── src/
    ├── app/
    │   ├── layout.tsx            # Root layout (Geist fonts, AppProvider)
    │   ├── page.tsx              # Overview: project grid with search/sort
    │   └── projects/[name]/page.tsx  # Project detail: conversation list
    ├── components/
    │   ├── ConversationCard.tsx  # Expandable card with metrics + chart
    │   ├── GradeBadge.tsx        # A/B/C/D/F colored badge
    │   ├── Header.tsx            # Sticky header with summary metrics
    │   ├── MessageList.tsx       # Color-coded message transcript
    │   ├── ProjectCard.tsx       # Project card with grade distribution
    │   └── TokenChart.tsx        # Recharts token progression chart
    ├── context/AppContext.tsx    # Global state: data, search, sort, theme
    └── lib/
        ├── types.ts              # TypeScript interfaces (mirrors JSON)
        └── utils.ts              # Formatting, filtering, sorting
```

## Quick Start

### Step 1: Generate conversation data (backend)

All `make` commands run from `backend/`:

```bash
cd backend

# First time: prompts for claude-code-log location, then runs full pipeline
make all

# Subsequent runs: cleanup → data generation → analysis
make all
```

**What `make all` does:**
1. **Setup** (`setup-cclog`) — Clones a claude-code-log fork if needed
2. **Update** (`update-cclog`) — Pulls latest from upstream (daaain/claude-code-log)
3. **Clean** (`clean-cclog-output`) — Deletes stale `full-transcripts.json` and HTML files
4. **Generate** (`generate-cclog-data`) — Creates fresh conversation data via cclog
5. **Analyze** (`conversations-analysis`) — Scores conversations, writes HTML + JSON

### Step 2: View results

**Option A — Static HTML** (no setup required):
```
open backend/output/analysis/index.html
```

**Option B — Next.js dashboard** (interactive, recommended):
```bash
# Export JSON for the frontend
cd backend && make frontend-export-json

# Start the dev server
cd frontend
pnpm install      # first time only
pnpm dev
```
Open [http://localhost:3000](http://localhost:3000). The dashboard provides:
- Overview page with project cards, grade distribution, total cost, and search/sort
- Per-project page with expandable conversation cards and token progression charts
- Dark/light theme toggle

### Individual pipeline steps

For debugging or partial updates:

```bash
cd backend
make setup-cclog           # Clone/verify claude-code-log exists
make update-cclog          # Pull latest from upstream
make clean-cclog-output    # Delete stale output files
make generate-cclog-data   # Generate full-transcripts.json files
make conversations-analysis # Analyze and generate reports
make frontend-export-json  # Copy JSON export to frontend/public/data/
```

### Configuration

On first run, `make setup-cclog` prompts for the claude-code-log clone location:
1. `~/work/claude-code-log` (recommended)
2. `~/.cache/claude-code-log`
3. Custom path

Your choice is saved in `backend/.cclog-config` (gitignored). To change it, delete the file and run `make setup-cclog` again.

### Custom analysis options

```bash
cd backend
uv run python -m src.app \
  --claude-projects ~/.claude/projects \
  --output output/analysis \
  --export-json output/analysis.json \
  --export-csv output/data.csv \
  --export-summary output/summary.json \
  --project-filter "permissions" \
  --verbose
```

### Troubleshooting

**"uv: command not found"**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**"Merge conflicts" when updating claude-code-log**
```bash
cd <cclog-dir> && git status
# or re-clone:
rm backend/.cclog-config && cd backend && make setup-cclog
```

**No conversation data generated**
- Verify `~/.claude/projects` contains project directories
- Check cclog: `cd <cclog-dir> && uv run python -m claude_code_log.cli --help`

**Frontend shows no data**
- Run `cd backend && make frontend-export-json` to generate `frontend/public/data/analysis-data.json`

## Development

### Backend (Python 3.13+, uv)

```bash
cd backend
make install-dev    # Install with dev dependencies (ruff, mypy)

make fmt            # Format with ruff (required before commits)
make lint           # Lint with ruff
make lint-fix       # Auto-fix lint issues
make type-check     # Type check with mypy (strict)
make check          # lint + type-check
```

### Frontend (Next.js, pnpm)

```bash
cd frontend
pnpm install        # Install dependencies
pnpm dev            # Dev server at localhost:3000
pnpm build          # Production build
pnpm lint           # Check with Biome
pnpm lint:fix       # Auto-fix lint issues
pnpm format         # Format with Biome
```

## Documentation

See `CLAUDE.md` for detailed documentation on:
- Architecture and data flow
- Cost calculation and token deduplication logic
- Conversation quality scoring weights
- How to add new metrics or export formats
- Frontend data flow (AppContext → components)