Metadata-Version: 2.4
Name: claude-recap
Version: 0.1.0
Summary: Recapture what you built with Claude — conversation history analyzer and report generator
Project-URL: Homepage, https://github.com/alexxu/claude-recap
Project-URL: Repository, https://github.com/alexxu/claude-recap
Project-URL: Issues, https://github.com/alexxu/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'
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** — Optional Claude API integration for intelligent narrative generation
- **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; the only network call is the opt-in `--ai` flag

## Getting Started

```bash
pip install claude-recap

# With AI summary support
pip install claude-recap[ai]
export ANTHROPIC_API_KEY=sk-ant-...
```

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

## 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 in your browser featuring an 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 (default)
claude-recap report -p monthly --purpose academic --ai       # 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 schedule` — Automate Reports

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

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

## 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 the `CLAUDE_HISTORY_DIR` environment variable. All processing happens locally. The optional `--ai` flag sends only condensed session metadata (not full conversations) to the Claude API for summary generation.

## Project Structure

```
src/claude_recap/
  cli.py           CLI commands (Click)
  parser.py        JSONL conversation parser
  analyzer.py      Statistics & time-series grouping
  reporter.py      Report rendering (HTML / Markdown / JSON)
  summarizer.py    AI summarization via Claude API
  server.py        Local dashboard server
templates/
  dashboard.html   Interactive dashboard template
  report.html      Report template
```

## Development

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

## License

[MIT](LICENSE)
