reflect

Reflect

Reflect: An AI tool to generate your brag document

[!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 💻

Run the setup script:

./bin/setup

On first run, this copies .env.example to .env and asks you to fill in your tokens. Edit .env, then re-run ./bin/setup to validate your environment. After validation, the script offers to encrypt your .env with dotenvx. If you accept, it creates a .env.keys file with your private decryption key. Keep .env.keys safe and never commit it.

Run the tool:

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

This will generate four markdown files in the output directory:

Features ✨

Usage 🛠️

Run the tool:

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

Example:

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

Arguments 📋

Required:

Date range (one required, mutually exclusive):

Optional:

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

Exclude specific repositories:

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

Environment Variables 🔐

Required environment variables:

To create a GitHub Personal Access Token:

  1. Go to GitHub Settings > Developer Settings > Personal Access Tokens > Tokens (classic)
  2. Generate a new token with the following scopes:
    • repo (Full control of private repositories)
    • read:org (Read organization data)
  3. Copy the token and add it to your .env file

Required for making LLM calls (one of):

Optional for using a different provider-compatible endpoint:

Encrypting & Decrypting .env 🔑

This project uses dotenvx for optional .env encryption.

Encrypt

npx @dotenvx/dotenvx encrypt

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

Decrypt

npx @dotenvx/dotenvx decrypt

This decrypts .env in-place, replacing encrypted values with plaintext. You can then delete .env.keys if you no longer need encryption.

Security Considerations 🔒

Output 📁

The script will generate one or more markdown files in the output directory:

output/contributions.md 📊

Contains:

output/summarized_contributions.md (with –brag flag) 📝

Contains:

output/brag_document.md (with –brag flag) 🎯

Contains:

Note: The output directory and all generated files are automatically git-ignored to prevent accidental commits.

Troubleshooting 🔍

If you get TypeScript errors, ensure you’re using Node.js v22 or higher:

node --version

If you get GitHub API errors:

If the script runs but generates an empty file:

If you get an error about the OpenAI API key:

If you get environment variable errors:

Claude Code Integration 🤖

This repository includes a Claude Code plugin that provides an interactive skill for working with Reflect. The skill helps with setup, running the CLI, and troubleshooting common issues.

Installing the Plugin

Add the marketplace and install the plugin:

/plugin marketplace add bostonaholic/reflect
/plugin install reflect@reflect

Or, if already working inside the Reflect repository, Claude Code automatically discovers the plugin from the .claude-plugin/ directory.

What the Skill Provides

Once installed, the reflect skill activates automatically when asking Claude Code about:

No slash commands or special syntax needed – just ask naturally (e.g., “how do I generate a brag document?” or “reflect is giving me an auth error”).

Links 🔗

This site is open source. Improve this page.