https://github.com/bostonaholic/reflect
An AI tool to generate your brag document
https://github.com/bostonaholic/reflect
ai brag-document llm nodejs
Last synced: 9 months ago
JSON representation
An AI tool to generate your brag document
- Host: GitHub
- URL: https://github.com/bostonaholic/reflect
- Owner: bostonaholic
- License: mit
- Created: 2025-03-29T15:36:47.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-09-10T02:21:00.000Z (9 months ago)
- Last Synced: 2025-09-10T16:04:32.227Z (9 months ago)
- Topics: ai, brag-document, llm, nodejs
- Language: TypeScript
- Homepage: https://bostonaholic.github.io/reflect/
- Size: 520 KB
- Stars: 34
- Watchers: 1
- Forks: 7
- Open Issues: 20
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://www.noidea.dog/glue), an excellent resource about the often-overlooked but essential work that makes teams successful.
## Quickstart 🚀
### Prerequisites ⚙️
1. Install [nodenv](https://github.com/nodenv/nodenv) (preferred) or [nvm](https://github.com/nvm-sh/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 your environment variables:
```bash
cp .env{.example,}
```
Run the setup script to configure your environment:
```bash
./script/setup
```
Run the tool:
```bash
./reflect --username --lookback --brag
```
This will generate three markdown files in the `output` directory:
- A detailed list of your GitHub 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:
```bash
./reflect --username --lookback [--brag]
```
Example:
```bash
./reflect --username bostonaholic --lookback 6 --brag
```
### Arguments 📋
**Required:**
- `--username `: Your GitHub username to fetch activity for
- `--lookback `: Number of months to look back for activity (must be a positive number)
**Optional:**
- `--provider `: LLM provider to use (e.g., openai, anthropic), defaults to openai
- `--model `: LLM model to use. For OpenAI (e.g., gpt-4, gpt-3.5-turbo), defaults to gpt-4o. For Anthropic (e.g., claude-3-7-sonnet-20250219), defaults to claude-3-7-sonnet-20250219
- `--brag`: Optional flag to generate a summary and brag document
- `--include-orgs `: Only include contributions from these organizations (mutually exclusive with --exclude-orgs)
- `--exclude-orgs `: Exclude contributions from these organizations (mutually exclusive with --include-orgs)
- `--include-repos `: Only include contributions from these repositories (mutually exclusive with --exclude-repos)
- `--exclude-repos `: Exclude contributions from these repositories (mutually exclusive with --include-repos)
### Examples 🚀
Basic usage:
```bash
./reflect --username bostonaholic --lookback 6 --brag
```
Choose a model:
```bash
./reflect --username bostonaholic --lookback 6 --model gpt-3-5-turbo --brag
```
Choose an LLM provider and model
```bash
./reflect --username bostonaholic --lookback 6 --provider anthropic --model claude-3-7-sonnet-20250219 --brag
```
Filter by specific organizations:
```bash
./reflect --username bostonaholic --lookback 6 --include-orgs shopify github
```
Exclude specific organizations:
```bash
./reflect --username bostonaholic --lookback 6 --exclude-orgs secret archived
```
Filter by specific repositories:
```bash
./reflect --username bostonaholic --lookback 6 --include-repos bostonaholic/reflect bostonaholic/dotfiles
```
Exclude specific repositories:
```bash
./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:
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):
- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`
Optional for using a different provider-compatible endpoint:
- `OPENAI_BASE_URL`
- `ANTHROPIC_BASE_URL`
## Security Considerations 🔒
- API keys are only accepted through environment variables, not command-line arguments
- All file operations are sanitized to prevent path traversal attacks
- GitHub API rate limits are properly handled with informative error messages
- Input validation is performed on all user-provided parameters
- Output files are restricted to a predefined list of allowed filenames
- GitHub tokens are never logged or exposed in error messages
## Output 📁
The script will generate one or more markdown files in the `output` directory:
### output/contributions.md 📊
Contains:
- A chronological list of your merged pull requests and closed issues
- Each item includes:
- Title
- Closing date
- Description/body
- Items are sorted by closing date (most recent first)
- Activity for the specified time period
### output/summarized_contributions.md (with --brag flag) 📝
Contains:
- A technical summary of your contributions
- Groups similar contributions together
- Highlights key technical changes and improvements
- Identifies patterns in the work
- Notes significant architectural changes
### output/brag_document.md (with --brag flag) 🎯
Contains:
- A professional brag document highlighting your achievements
- Focuses on business impact and value
- Emphasizes collaboration and leadership
- Highlights key metrics and improvements
- Suitable for performance reviews or portfolio
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:
```bash
node --version
```
If you get GitHub API errors:
- Verify your GitHub Personal Access Token (PAT) is correctly set in your `.env` file
- Check that your PAT has the required scopes (`repo` and `read:org`)
- Ensure your PAT hasn't expired (they can be set to expire after a certain time)
- Verify you have access to the repositories you're trying to fetch data from
If the script runs but generates an empty file:
- Check that you have activity in the specified time period
- Verify your GitHub username is correct
- Ensure you have the necessary permissions to access the repositories
If you get an error about the OpenAI API key:
- Make sure you've set it in your `.env` file
- Check that the API key is valid and has sufficient credits
- Verify the .env file is in the correct location
If you get environment variable errors:
- Ensure your `.env` file exists and is properly formatted
- Check that there are no spaces around the `=` sign in your `.env` file
- Verify the `.env` file is in the root directory of the project
## Links 🔗
- 🗞️ [Hacker News](https://news.ycombinator.com/item?id=43519484)
- 🐦 [X](https://x.com/bostonaholic/status/1906119726948073824)
- 💼 [LinkedIn](https://www.linkedin.com/posts/bostonaholic_github-bostonaholicreflect-an-ai-tool-activity-7311885477546991616-JDzT)