code-recap 1.3.1

Git activity analysis and LLM-powered summary tools for developers and consultants

Generate beautiful activity reports, client summaries, and blog posts from your git history—powered by LLMs.

Quick Start • Use Cases • Commands • Configuration

---

What It Does

Code Recap helps developers and consultants who work across multiple repositories:

📊 Year-in-Review Reports — Generate polished summaries of your work for clients, complete with statistics, achievements, and technology breakdowns. Export as Markdown or HTML.

⏱️ Daily Time Logging — Quickly summarize what you worked on today (or any day) for billing and time tracking. No more digging through commits.

✍️ Blog Post Generation — Turn your commits into technical blog posts. The AI researches your changes and drafts content with real code examples.

📈 Activity Statistics — Track commits, lines changed, languages used, and coding streaks across all your projects.

🗂️ Multi-Client Organization — Automatically group repositories by client using pattern matching. Each client gets their own reports.

📝 Example Output

See what generated reports look like:

For consultants with multiple clients:

• Client Reports (HTML) — Browse the styled HTML version
• Monthly summary (markdown)
• Annual client summary (markdown)

For solo developers or internal work:

• Solo Reports (HTML) — Without client organization
• Monthly summary (markdown)
• Annual summary (markdown)

---

Quick Start

# Initialize (creates config, prompts for API keys, shows next steps)
uvx code-recap init

# Or set API key manually
export OPENAI_API_KEY='sk-...'

# Generate your year-in-review
cd ~/Documents/Repos
uvx code-recap summarize 2025 --open
# → Output: ./code-recap-2025/

That's it! Your reports open automatically in the browser.

Installation Options

# Run directly (no install)
uvx code-recap summarize 2025

# Or install globally
uv tool install code-recap    # then use: code-recap summarize ...
pip install code-recap        # then use: code-recap summarize ...

---

Use Cases

Year-end report with HTML

code-recap summarize 2025 --open
# → Reports saved to ./code-recap-2025/ (markdown + HTML)

Daily time logging

code-recap daily --date yesterday

Blog post from your commits

code-recap blog full "Building a Custom Protocol" --period 2025-Q3

Multi-year statistics (CSV export)

code-recap stats 2020:2025 --granularity year --format csv

---

How It Works

Run code-recap from a directory containing git repositories:

~/Documents/Repos/           # Run code-recap here (or use --root <path>)
├── project-a/               # Git repository (scanned)
├── project-b/               # Git repository (scanned)
├── side-project/            # Git repository (scanned)
└── code-recap-2025/         # Generated report (or use --output-dir to specify a different directory)
    ├── summary-2025.md
    └── html/
        └── index.html

No configuration needed for basic use. Just run the command and get a unified report.

For multi-client workflows, create a config file:

code-recap init              # Creates config.yaml + API key setup

See the Configuration Guide for full details.

---

Recommended Models

Code Recap uses LiteLLM to support multiple LLM providers:

Model	Command	Best For	Cost
GPT-4o-mini	--model gpt-4o-mini	Default choice, reliable and fast	~$0.10/year
Gemini 2.5 Flash	--model gemini/gemini-2.5-flash	Large codebases (1M context), very fast	~$0.25/year
Gemini 3 Flash	--model gemini/gemini-3-flash-preview	Latest Gemini model	~$0.40/year
Claude 4.5 Haiku	--model claude-haiku-4-5	Best writing quality for summaries	~$0.75/year

Costs shown are approximate for summarizing 1 year of typical developer activity (~3000 commits).

code-recap summarize 2025 --list-models    # See all available models

---

Commands

Command	Description
summarize	LLM-powered activity summaries (main command)
daily	Daily activity for time logging
stats	Statistics without LLM (text/markdown/CSV)
html	Convert markdown to HTML reports
blog	Generate blog posts from commits
deploy	Deploy HTML reports to providers
git	Repository utilities (fetch, archive)

See the Command Reference for detailed options.

---

Documentation

• Configuration Guide — Client mapping, API keys, exclusions, HTML styling
• Command Reference — Detailed options for all CLI commands
• Deployment Guide — Deploy and share HTML reports
• Extending Code Recap — Implement custom deployment providers
• Example Configuration — Full config with all options documented

---

Installation

Using uv (Recommended)

# Install as a tool
uv tool install code-recap

# Or run directly without installing
uvx code-recap summarize 2025

Using pip

pip install code-recap

Development

git clone https://github.com/nrb-tech/code-recap.git
cd code-recap
uv sync --dev

# Run linting
uv run ruff check .
uv run ruff format .

Requirements

• Python 3.9+
• Git (command line)

---

License

MIT License - see LICENSE for details.

---

Built by NRB Tech