Metadata-Version: 2.4
Name: claude-recap
Version: 0.2.0
Summary: Recapture what you built with Claude — conversation history analyzer and report generator
Project-URL: Homepage, https://github.com/MazelTovy/claude-recap
Project-URL: Repository, https://github.com/MazelTovy/claude-recap
Project-URL: Issues, https://github.com/MazelTovy/claude-recap/issues
Author: Alex Xu
License-Expression: MIT
License-File: LICENSE
Keywords: ai,analytics,claude,dashboard,recap,report
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: ai
Requires-Dist: anthropic>=0.40; extra == 'ai'
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: openai>=1.0; extra == 'all'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Description-Content-Type: text/markdown

<p align="center">
  <h1 align="center">Claude Recap</h1>
  <p align="center">
    Recapture what you built with Claude Code.
    <br />
    <a href="README-cn.md">中文文档</a>
  </p>
</p>

<p align="center">
  <a href="https://pypi.org/project/claude-recap/"><img src="https://img.shields.io/pypi/v/claude-recap?color=blue" alt="PyPI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.9+-blue" alt="Python 3.9+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
</p>

---

Turn your local Claude Code conversation history into **interactive dashboards**, **periodic reports**, and **AI-powered summaries** — all without sending raw conversations anywhere.

## Features

- **Interactive Dashboard** — GitHub-style activity heatmap, project breakdown, filterable session browser
- **AI-Powered Summaries** — Anthropic, OpenAI, or any OpenAI-compatible API (ollama, vllm, together, deepseek, groq, ...)
- **Smart Token Optimization** — Auto-sampling and progressive compression for large histories
- **Statistical Summaries** — Useful reports even without AI: streak analysis, peak periods, project rankings
- **Multi-period Reports** — Daily / Weekly / Monthly / Yearly
- **Purpose-driven Exports** — General, Academic, Job Search, Work Report modes
- **Multiple Formats** — Self-contained HTML, Markdown, JSON
- **Cross-platform** — macOS, Linux, Windows — auto-detects Claude data directory
- **Privacy-first** — Runs entirely on your machine; network calls only when you opt in

## Getting Started

```bash
pip install claude-recap
```

```bash
claude-recap                  # quick usage stats
claude-recap serve            # launch interactive dashboard
claude-recap report --open    # generate & open a weekly HTML report
```

Reports include a statistical summary by default — no API key required.

## AI Setup (Optional)

Use any LLM provider for richer narrative summaries:

```bash
claude-recap config --setup
```

Interactive setup walks you through choosing a provider:

| # | Provider | Install | Example |
|---|----------|---------|---------|
| 1 | **Anthropic** (Claude) | `pip install claude-recap[ai]` | Claude Sonnet / Opus |
| 2 | **OpenAI** | `pip install claude-recap[openai]` | GPT-4o / GPT-4o-mini |
| 3 | **OpenAI-compatible** | `pip install claude-recap[openai]` | ollama, vllm, together, deepseek, groq, etc. |

Or install everything: `pip install claude-recap[all]`

**Using environment variables** (alternative to `config --setup`):

```bash
# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...

# OpenAI
export OPENAI_API_KEY=sk-...

# OpenAI-compatible (e.g. ollama)
export OPENAI_API_KEY=not-needed
export OPENAI_BASE_URL=http://localhost:11434/v1
export CLAUDE_RECAP_MODEL=llama3
export CLAUDE_RECAP_PROVIDER=openai
```

Then generate reports with AI:

```bash
claude-recap report --ai                    # AI-enhanced report
claude-recap report --ai --purpose academic # AI academic report
```

## Usage

### `claude-recap` — Quick Stats

```
$ claude-recap
╭──────────────────────╮
│ Claude Recap v0.1.0  │
╰── 2026-03-10 → 04-04 ╯
  Sessions        42
  Messages      2665
  Active Days     18
  Projects        12
```

### `claude-recap serve` — Interactive Dashboard

```bash
claude-recap serve [--port 6275]
```

Opens a local dashboard with activity heatmap, messages-per-day chart, project & tool breakdown, session browser with filters, and an AI Insights button.

### `claude-recap report` — Generate Reports

```bash
claude-recap report                                          # weekly HTML + stats summary
claude-recap report --ai -p monthly --purpose academic       # monthly academic + AI summary
claude-recap report --from 2026-01-01 --to 2026-03-31       # custom date range
claude-recap report -f markdown --purpose work_report        # Markdown work report
```

| Purpose | Focus |
|---------|-------|
| `general` | Overall activity and key conversations |
| `academic` | Research activities, experiments, methodologies |
| `job_search` | Technical skills, tools used, problem complexity |
| `work_report` | Deliverables, productivity, project progress |

### `claude-recap config` — Manage AI Provider

```bash
claude-recap config --setup   # interactive provider setup
claude-recap config --show    # show current config
claude-recap config --set-key # update API key only
```

### `claude-recap schedule` — Automate Reports

```bash
claude-recap schedule --period weekly
```

Prints platform-specific cron / Task Scheduler instructions for recurring report generation.

## Token Optimization

For users with large conversation histories, Claude Recap automatically:

1. **Samples strategically** — keeps all recent sessions (last 14 days), uniformly samples older ones (cap: 200 sessions)
2. **Compresses progressively** — if the prompt exceeds the token budget, reduces topic count and content length in stages
3. **Shows estimates** — displays estimated token count before making API calls

This means even with thousands of sessions, a single API call stays within reasonable bounds.

## How It Works

Claude Recap reads the JSONL conversation logs stored locally by Claude Code:

| Platform | Default Location |
|----------|-----------------|
| macOS / Linux | `~/.claude/` |
| Windows | `%LOCALAPPDATA%\claude\` or `%APPDATA%\claude\` |

Override with `--dir` or `CLAUDE_HISTORY_DIR`. All processing happens locally. The optional `--ai` flag sends only condensed session metadata (not full conversations) to your configured LLM provider.

## Development

```bash
git clone https://github.com/MazelTovy/claude-recap.git
cd claude-recap
pip install -e ".[all]"
```

## License

[MIT](LICENSE)
