gitbrief 0.4.0

Git-history-aware codebase context generator for LLMs

gitbrief

Generate LLM-ready context from any git repository — in seconds.

gitbrief . --budget 8000 --clipboard              # copy to clipboard, ready to paste into Claude/GPT
gitbrief . --format xml                           # Claude-optimized XML output
gitbrief . --tree --prompt "Review for security"  # add directory tree + custom instruction
gitbrief . --changed-only --clipboard             # PR review: only files changed vs main
gitbrief . --changed-only --include-diff          # full PR context: diff + changed file contents

---

The problem

Every developer using LLMs (Claude, GPT, Gemini) manually copies code into chat windows. You paste some files, forget others, include outdated versions, blow the context window, and guess at what's relevant.

This is wasted engineering time.

The solution

gitbrief reads your git history to understand what's actually important right now, then packs the right files into a token-budget-aware document — perfect for pasting into any LLM.

$ gitbrief . --budget 8000 --stats

╭────────────────────────────╮
│ gitbrief allocation stats │
╰────────────────────────────╯
Token budget: 8,000 | Used: 7,999 (100%)
Files included: 6   | Skipped (budget): 194
Git commits analyzed: 100 | Branch: main

Top files by priority:
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━┓
┃ File                      ┃ Priority ┃ Tokens ┃ Changed? ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━┩
│ src/auth/middleware.py    │     0.95 │    432 │ 🔥       │
│ src/auth/tokens.py        │     0.91 │    318 │ 🔥       │
│ README.md                 │     0.83 │  1,240 │ 🔥       │
│ pyproject.toml            │     0.75 │    168 │ —        │
└───────────────────────────┴──────────┴────────┴──────────┘

Files marked 🔥 were modified in recent commits. The most relevant context surfaces automatically.

---

Why gitbrief beats alternatives

Feature	gitbrief	repomix	llm-ctx	manual
Git-history-aware ranking	✅	❌	❌	❌
Token budget control	✅	❌	partial	❌
Recency decay scoring	✅	❌	❌	❌
Recent commits narrative	✅	❌	❌	❌
PR review mode (changed files only)	✅	❌	❌	❌
Include git diff in output	✅	❌	❌	❌
Single command	✅	✅	✅	❌
--clipboard flag	✅	❌	❌	❌
XML output (Claude-optimized)	✅	❌	❌	❌
Directory tree in output	✅	✅	❌	❌
Append custom instruction	✅	❌	❌	❌

---

Install

pip install gitbrief

Requires Python 3.10+ and optionally a git repository.

---

Usage

# Basics
gitbrief .                          # current repo, 32k token budget
gitbrief /path/to/repo              # any repo

# Token budget control
gitbrief . --budget 8000            # fits GPT-4 32k
gitbrief . --budget 128000          # Claude 3.5 / GPT-4o full context

# Output
gitbrief . -o context.md            # write to file
gitbrief . --clipboard              # copy to clipboard (macOS/Linux/Windows)
gitbrief . | pbcopy                 # macOS: pipe to clipboard

# Format
gitbrief . --format xml             # Claude-optimized XML output (uses <documents> structure)
gitbrief . --format markdown        # default markdown output

# Filter
gitbrief . --no-tests               # skip test files (save tokens)

# PR review mode (v0.4+)
gitbrief . --changed-only                        # only files changed vs base branch (auto-detected)
gitbrief . --changed-only --base develop         # diff against a specific branch
gitbrief . --include-diff                        # add git diff to output
gitbrief . --changed-only --include-diff --clipboard  # ultimate PR review context

# Add context for LLM
gitbrief . --tree                   # include ASCII directory tree
gitbrief . --prompt "Review for security vulnerabilities"  # append instruction to context
gitbrief . --tree --prompt "What tests are missing?" --clipboard  # combine everything

# Debug
gitbrief . --stats                  # print allocation table to stderr
gitbrief . --max-commits 200        # analyze more git history

---

How ranking works

gitbrief assigns each file a priority score (0–1):

• Recency (60%): exponential decay — files changed today = 1.0, untouched 6 months = ~0.25
• Frequency (40%): normalized commit frequency across history
• Recency bonus: +0.2 if the file appeared in the most recent 20% of commits
• Type bonuses: README (+0.1), config files (+0.15)

Files are sorted by priority and greedily selected within your token budget.

---

Development

git clone https://github.com/faw21/gitbrief
cd gitbrief
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/   # 38 tests, 93% coverage

---

License

MIT