🏆 Brag CLI

Stop forgetting your wins. Start bragging.

A command-line tool with Raycast integration for tracking professional accomplishments. Perfect for performance reviews, 1:1s, and remembering that you actually do get stuff done.

🎨 This project was vibe-coded - built with AI assistance on a creative coding journey. PRs and contributions are welcome!

✨ Features

• 📁 Local-first: Your brags stay on your machine (~/.brag/data/)
• ⚡ Lightning fast: Add a brag in seconds from terminal or Raycast
• 🤖 AI-friendly: JSONL format is perfect for LLM analysis
• 🎨 Raycast UI: Beautiful interface for quick capture and search
• 📦 Zero dependencies: Python CLI uses only stdlib

🚀 Quick Start

Install the CLI (Recommended: uv)

# Clone
git clone <repo-url>
cd brag

# Install (uses uv tool install under the hood)
chmod +x install.sh
./install.sh

# 🎉 You're ready to brag!
brag add "Set up the brag CLI - already winning!"

Note: If you don’t have uv installed yet, run ./install.sh --install-uv (or install via Homebrew: brew install uv).

Note (macOS): On a fresh Mac, installing Python (or running python3) may trigger a prompt to install Xcode Command Line Tools.

Install Raycast Extension (Optional)

# Prompted install:
./install.sh

# Or fully automatic:
./install.sh --raycast

📝 Usage

Record your wins

# Quick brag
brag add "Shipped the new auth service"

# Interactive mode (avoids shell quoting issues!)
brag add
# 🏆 What did you accomplish? (Press Enter twice to save)

# With metadata
brag add "Fixed critical bug" --tags bug,urgent --project payments

# Multi-line (opens your editor)
brag add --edit

💡 Tip: If your shell gives you trouble with ! or other special characters, just run brag add with no arguments for interactive input!

Review your accomplishments

# What did I do this week?
brag list

# What about this month?
brag list --days 30

Export for performance reviews

# Get everything as JSON (great for AI analysis)
brag export --format json

# Markdown for docs
brag export --format markdown --start 2024-01-01

# Just Q4
brag export --start 2024-10-01 --end 2024-12-31

🗂️ Data Storage

Your brags live in ~/.brag/data/ organized by date:

~/.brag/data/
  2025/
    12/
      09.jsonl  ← One file per day
      10.jsonl
      11.jsonl

Each entry is a single JSON line:

{"timestamp": "2025-12-09T17:00:00Z", "content": "Shipped auth service", "tags": ["feature"], "project": "auth"}

🗑️ Uninstall

Changed your mind? No hard feelings!

./uninstall.sh

This will:

• Remove the CLI from pip
• Clean up your shell PATH
• Remove Raycast extension files
• Optionally delete your brag data (you'll be asked)

🎯 Why Brag?

Because when review season comes around, you'll thank yourself for having a record of:

• That bug you fixed at 2am
• The feature that seemed small but took a week
• The time you helped onboard the new team member
• All those "quick" tasks that added up

Your future self will thank you. Start bragging today.

📚 Documentation

• INSTALL.md - Detailed installation guide
• RAYCAST_INTEGRATION.md - Raycast extension setup
• CONTRIBUTING.md - How to contribute
• DEVELOPMENT.md - Development setup
• ARCHITECTURE.md - Technical deep-dive

🙏 Acknowledgments

Thanks to @gleeblezoid for the original idea and the perfect name. The concept of a "brag document" for tracking accomplishments is brilliant, and this tool wouldn't exist without that inspiration.

---

Built with ❤️ for developers who forget how awesome they are.