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 "jane@example.com"

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 "me@example.com"

# 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