Claude Recap

Recapture what you built with Claude Code.
中文文档

---

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

pip install claude-recap

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:

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):

# 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:

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

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

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

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

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

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

License

MIT