<div align="center">

git-glimpse

Token-budgeted Git status, diffs, and logs for AI agents via CLI and MCP.

<img src="demo.gif" alt="Demo" width="700" />

</div>

---

🎯 Why?

AI coding agents constantly need Git context, but raw git diff/log/status output can consume tens of thousands of tokens and overflow agent context windows. Existing Git MCP servers usually expose raw commands or full output; there is no small read-only adapter focused specifically on budgeted, agent-safe repository context.

Target audience: Developers building AI coding agents, MCP servers, Claude Code/Cursor workflows, and CLI power users who want compact Git context without flooding LLM context windows.

✨ Features

• ✨ Token-budgeted Git status output with branch, changed files, and untracked summary
• ✨ Token-budgeted Git diff output that truncates huge sections and lists omitted files
• ✨ Token-budgeted Git log output with shortstat
• ✨ Read-only MCP stdio server exposing glimpse_status, glimpse_diff, and glimpse_log tools
• ✨ Single-file Python CLI usable directly from shell or scripts

🚀 Quick Start

# Install
pip install git-glimpse

# Run
git-glimpse --help

📦 Installation

From Source

git clone https://github.com/YOUR_USERNAME/git-glimpse.git
cd git-glimpse

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest -v

🎬 Demo

The GIF above was recorded using Charm VHS:

vhs < demo.tape

📖 Usage

# Show help
git-glimpse --help

# Common usage examples
git-glimpse --example

🏗️ Architecture

graph LR
    A[Input] --> B[Core Engine]
    B --> C[Output]
    B --> D[Plugins]
    D --> E[Extensions]

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

MIT © 2026 — See LICENSE for details.

---

<div align="center">

If this project helped you, please ⭐ star it!

Made with ❤️ and AI

</div>