Metadata-Version: 2.4
Name: gitbrief
Version: 0.2.0
Summary: Git-history-aware codebase context generator for LLMs
Project-URL: Homepage, https://github.com/faw21/gitbrief
Project-URL: Repository, https://github.com/faw21/gitbrief
Project-URL: Issues, https://github.com/faw21/gitbrief/issues
Author: faw21
License: MIT
License-File: LICENSE
Keywords: ai,context,developer-tools,git,llm
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: gitpython>=3.1
Requires-Dist: pathspec>=0.11
Requires-Dist: rich>=13.0
Requires-Dist: tiktoken>=0.5
Provides-Extra: dev
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Description-Content-Type: text/markdown

# gitbrief

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

```bash
gitbrief . --budget 8000 --clipboard   # copy to clipboard, ready to paste into Claude/GPT
gitbrief . --format xml                # Claude-optimized XML output
```

[![PyPI version](https://img.shields.io/pypi/v/gitbrief.svg)](https://pypi.org/project/gitbrief/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Tests](https://img.shields.io/badge/tests-38%20passing-brightgreen.svg)](https://github.com/faw21/gitbrief)

---

## 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 | ✅ | ❌ | ❌ | ❌ |
| Single command | ✅ | ✅ | ✅ | ❌ |
| `--clipboard` flag | ✅ | ❌ | ❌ | ❌ |
| XML output (Claude-optimized) | ✅ | ❌ | ❌ | ❌ |

---

## Install

```bash
pip install gitbrief
```

Requires Python 3.10+ and optionally a git repository.

---

## Usage

```bash
# 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)

# 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

```bash
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
