recap

A CLI tool that generates fair, unbiased engineering reviews from your GitHub activity.

Overview

Recap pulls your GitHub activity — PRs authored, PRs reviewed, commits, and PR comments — for a given time period and produces both a structured text report and an AI-generated engineering review. The AI summary evaluates your work honestly: what you shipped, quality signals, scope relative to the time period, collaboration patterns, strengths, and areas for improvement.

It handles GitHub's 1000-result search limit by automatically splitting date ranges and paginates through all results. Organization filtering lets you scope reports to a specific org.

Install

npm i @clanki/recap -g
bun i @clanki/recap -g
# or your favorite package manager

Prerequisites

• GitHub auth (one of the following):
  • The GitHub CLI (gh) installed and authenticated — recap will use it automatically
  • A GITHUB_TOKEN or GH_TOKEN environment variable with read access to your repos and PRs
• The claude CLI installed locally (used to generate AI summaries)

Usage

Run recap with no arguments to start interactive mode, which walks you through the options:

recap

Quick roast

Get a comedic roast of your recent GitHub activity:

recap roast

Full options

recap [options]

| Flag | Description | Default | |------|-------------|---------| | -t, --period <period> | Time period: week, month, quarter, year, or custom | week | | -s, --since <date> | Start date (YYYY-MM-DD), required with --period custom | — | | -u, --until <date> | End date (YYYY-MM-DD), required with --period custom | — | | -f, --format <format> | Output format: text, summary, or both | both | | --username <username> | GitHub username (defaults to the token owner) | — | | -o, --org <org> | Filter by GitHub organization | — | | -p, --prompt <prompt> | Custom prompt (replaces default review prompt; activity data is appended) | — | | -i, --interactive | Force interactive mode | — |

Examples

# Last week's recap (default)
recap

# Last quarter, text only
recap -t quarter -f text

# Custom date range for a specific org
recap -t custom -s 2025-01-01 -u 2025-03-31 -o my-org

# AI summary only for the past month
recap -t month -f summary

# Custom prompt
recap -p "Summarize this developer's work in 3 bullet points."

# Roast your last month of work
recap roast

# Roast scoped to an org
recap roast -o my-org