bragbot

Generate brag documents from your git history. Inspired by Julia Evans' blog post on brag documents.

Installation

npm install -g @naamanu/bragbot

Usage

One-time Generation

Generate a brag document for any git repository:

# Current directory, last month
bragbot

# Specific repo and date range
bragbot /path/to/repo --since "2025-01-01" --until "2025-06-30"

# Output to specific file
bragbot -o my-brag.md

# Output to stdout (for piping)
bragbot --stdout | less

# Filter by author
bragbot --author "[email protected]"

Options

| Option | Description | |--------|-------------| | -s, --since <date> | Start date (default: "1 month ago") | | -u, --until <date> | End date (default: "today") | | -a, --author <name> | Filter by author name/email | | -o, --output <file> | Output file (default: brag-<start>-to-<end>.md) | | --stdout | Output to stdout instead of file |

Background Daemon

Run bragbot as a background service to automatically collect daily brag documents.

Add Repositories to Watch

# Add a repo with auto-detected settings
bragbot daemon add /path/to/repo

# Add with custom name and author filter
bragbot daemon add /path/to/repo --name "My Project" --author "[email protected]"

# Add with custom output directory
bragbot daemon add /path/to/repo --output-dir ~/brags

Manage Watched Repos

# List all watched repositories
bragbot daemon list

# Remove a repository
bragbot daemon remove /path/to/repo

Configure Schedule

# Run daily at 9 AM (default)
bragbot daemon schedule daily

# Run weekly (Mondays at 9 AM)
bragbot daemon schedule weekly

# Run at specific hour (0-23)
bragbot daemon schedule 17  # 5 PM

Start/Stop Daemon

# Start background daemon
bragbot daemon start

# Check status
bragbot daemon status

# Stop daemon
bragbot daemon stop

# Run collection once (without daemon)
bragbot daemon run

Configuration

All daemon configuration is stored in ~/.bragbot/:

| File | Description | |------|-------------| | config.json | Watched repos and schedule | | daemon.pid | Process ID of running daemon | | daemon.log | Daemon logs | | brags/ | Default output directory for collected brags |

Output Format

Bragbot generates a structured markdown document with:

• Summary - Total commits, branches, and identified themes (features, bug fixes, etc.)
• Work by Branch/Feature - Grouped commits with full commit descriptions
• Detailed Commit Log - Table of all commits with dates, hashes, and messages

All data is read from local git history - no external requests are made.

Development

# Install dependencies
bun install

# Run in development
bun run dev

# Build for production
bun run build

License

MIT