https://github.com/naamanu/bragbot
Generate brag documents from your git history
https://github.com/naamanu/bragbot
brag-document cli devtools
Last synced: 19 days ago
JSON representation
Generate brag documents from your git history
- Host: GitHub
- URL: https://github.com/naamanu/bragbot
- Owner: naamanu
- License: mit
- Created: 2026-01-13T13:51:50.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-01-13T18:43:33.000Z (6 months ago)
- Last Synced: 2026-05-01T19:07:07.788Z (2 months ago)
- Topics: brag-document, cli, devtools
- Language: TypeScript
- Homepage:
- Size: 145 KB
- Stars: 8
- Watchers: 1
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# bragbot
Generate brag documents from your git history. Inspired by [Julia Evans' blog post on brag documents](https://jvns.ca/blog/brag-documents/).
## Installation
```bash
npm install -g @naamanu/bragbot
```
## Usage
### One-time Generation
Generate a brag document for any git repository:
```bash
# 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 ` | Start date (default: "1 month ago") |
| `-u, --until ` | End date (default: "today") |
| `-a, --author ` | Filter by author name/email |
| `-o, --output ` | Output file (default: `brag--to-.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
```bash
# 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
```bash
# List all watched repositories
bragbot daemon list
# Remove a repository
bragbot daemon remove /path/to/repo
```
#### Configure Schedule
```bash
# 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
```bash
# 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
```bash
# Install dependencies
bun install
# Run in development
bun run dev
# Build for production
bun run build
```
## License
MIT