Reflect | reflect

reflect

Reflect

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

Quickstart 🚀

Prerequisites ⚙️

Install nodenv (preferred) or nvm

Install npm or yarn package manager

GitHub Personal Access Token (PAT) with repo and read:org scopes

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<br>.env.example to .env if it doesn’t exist. Edit<br>.env with your tokens.

Run the tool:

./reflect --username --lookback --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 --lookback [--brag]

Example:

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

Arguments 📋

Required:

--username : Your GitHub username to fetch activity for

Date range (one required, mutually exclusive):

--lookback : Number of months to look back for activity (1-36)

--since : Start date in YYYY-MM-DD<br>format; fetches activity from this date to today

--start-date + --end-date :<br>Specify an exact date range (both required)

Optional:

--provider : LLM provider to use<br>(e.g., openai, anthropic), defaults to openai

--model : LLM model to use. For OpenAI<br>(e.g., gpt-5.5, gpt-5.5-mini), defaults to<br>gpt-5.5. For Anthropic (e.g.,<br>claude-opus-4-7, claude-sonnet-4-6), defaults<br>to claude-opus-4-7

--brag: Optional flag to generate a summary and brag document

--roast: Optional flag to generate a humorous roast document

--include-orgs : Only include<br>contributions from these organizations<br>(mutually exclusive with –exclude-orgs)

--exclude-orgs : Exclude<br>contributions from these organizations<br>(mutually exclusive with –include-orgs)

--include-repos : Only include<br>contributions from these repositories<br>(mutually exclusive with –exclude-repos)

--exclude-repos : Exclude<br>contributions from these repositories<br>(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 \<br>--lookback 6 --provider anthropic \<br>--model claude-opus-4-7 --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 \<br>--lookback 6 \<br>--include-repos bostonaholic/reflect \<br>bostonaholic/dotfiles

Generate a roast document:

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

Exclude specific repositories:

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

Environment Variables 🔐

Required environment variables:

GITHUB_TOKEN: Your GitHub Personal Access Token (required)

To create a GitHub Personal Access Token:

Go to GitHub Settings > Developer Settings ><br>Personal Access Tokens > Tokens (classic)

Generate a new token with the following scopes:

repo (Full control of private repositories)

read:org (Read organization data)

Copy the token and add it to your .env file

Required for making LLM calls (one of):

OPENAI_API_KEY

ANTHROPIC_API_KEY

Optional for using a different provider-compatible endpoint:

OPENAI_BASE_URL

ANTHROPIC_BASE_URL

Encrypting & Decrypting .env 🔑

This project uses dotenvx<br>for optional .env encryption.

Encrypt

npx @dotenvx/dotenvx encrypt

This encrypts the values in .env in-place and<br>creates a .env.keys file containing your private<br>decryption key. Keep .env.keys safe and never<br>commit it.

Decrypt

npx @dotenvx/dotenvx decrypt

This decrypts .env in-place, replacing...