reflect

Reflect

[!IMPORTANT] While this tool helps document your GitHub contributions, it's crucial to remember that your impact and value to a company extends far beyond what's visible in GitHub. Many critical aspects of software engineering - such as mentoring, documentation, cross-team collaboration, and technical leadership - often happen outside of version control. For more on this topic, check out Glue Work, an excellent resource about the often-overlooked but essential work that makes teams successful.

Quickstart 🚀

Prerequisites ⚙️

1. Install nodenv (preferred) or nvm
2. Install npm or yarn package manager
3. GitHub Personal Access Token (PAT) with repo and read:org scopes
4. OpenAI API key (optional, for summary and brag document generation)

Usage 💻

Set up the development environment:

dev up

This installs Node.js, npm dependencies, and copies .env.example to .env if it doesn't exist. Edit .env with your tokens.

Run the tool:

./reflect --username <github-username> --lookback <months-to-look-back> --brag

This will generate four markdown files in the output directory:

• A detailed list of your GitHub contributions
• A report of your PR review contributions
• A summarized version of your contributions
• A professional brag document highlighting your achievements

Features ✨

• 📥 Fetches merged pull requests and closed issues from GitHub
• 🔍 Filters by author and date range (last 6 months by default)
• 📝 Generates a clean, chronological markdown document
• 🔄 Combines both PRs and issues into a single reflection document
• ⚡ Uses GitHub's official Octokit API client for efficient data retrieval
• 🤖 Optional AI-powered summary and brag document generation
• 🔒 Secure handling of API keys and sensitive data

Usage 🛠️

Run the tool:

./reflect --username <github-username> --lookback <months-to-look-back> [--brag]

Example:

./reflect --username bostonaholic --lookback 6 --brag

Arguments 📋

Required:

• --username <username>: Your GitHub username to fetch activity for

Date range (one required, mutually exclusive):

• --lookback <number>: Number of months to look back for activity (1-36)
• --since <date>: Start date in YYYY-MM-DD format; fetches activity from this date to today
• --start-date <date> + --end-date <date>: Specify an exact date range (both required)

Optional:

• --provider <provider>: LLM provider to use (e.g., openai, anthropic), defaults to openai
• --model <model>: LLM model to use. For OpenAI (e.g., gpt-4.1, gpt-4.1-mini), defaults to gpt-4.1. For Anthropic (e.g., claude-sonnet-4-6, claude-sonnet-4-5), defaults to claude-sonnet-4-6
• --brag: Optional flag to generate a summary and brag document
• --roast: Optional flag to generate a humorous roast document
• --include-orgs <orgs...>: Only include contributions from these organizations (mutually exclusive with --exclude-orgs)
• --exclude-orgs <orgs...>: Exclude contributions from these organizations (mutually exclusive with --include-orgs)
• --include-repos <repos...>: Only include contributions from these repositories (mutually exclusive with --exclude-repos)
• --exclude-repos <repos...>: Exclude contributions from these repositories (mutually exclusive with --include-repos)

Examples 🚀

Basic usage:

./reflect --username bostonaholic --lookback 6 --brag

Fetch activity since a specific date:

./reflect --username bostonaholic --since 2025-01-01 --brag

Choose a model:

./reflect --username bostonaholic --lookback 6 --model gpt-3-5-turbo --brag

Choose an LLM provider and model

./reflect --username bostonaholic \
  --lookback 6 --provider anthropic \
  --model claude-sonnet-4-6 --brag

Filter by specific organizations:

./reflect --username bostonaholic --lookback 6 --include-orgs shopify github

Exclude specific organizations:

./reflect --username bostonaholic --lookback 6 --exclude-orgs secret archived

Filter by specific repositories:

./reflect --username bostonaholic \
  --lookback 6 \
  --include-repos bostonaholic/reflect \
  bostonaholic/dotfiles

Generate a roast document:

./reflect --username bostonaholic --lookback 6 --roast

Exclude specific repositories:

./reflect --username bostonaholic \
  --lookback 6 \
  --exclude-repos bostonaholic/secret \
  bostonaholic/archived

Environment Variables 🔐

Required environment variables:

• GITHUB_TOKEN: Your GitHub Personal Access Token (required)

To create a GitHub Personal Access Token: