GitLens AI

GitLens AI allows you to ask natural language questions about your Git repository history. GitLens AI first indexes your commits into a semantic vector database and uses an LLM agent to retrieve and reason over them, so you can ask questions like "when was the auth middleware rewritten and why?" instead of grepping through git log.

How it works

1. On first launch, all commits (including full diffs) are extracted via git log -p and embedded using Voyage AI into a local FAISS index.
2. On subsequent launches, only new commits since the last run are embedded and merged into the existing index — no full rebuild.
3. At query time, a LangGraph agent decides whether to call the retriever tool, fetches the most semantically relevant commits, and synthesises an answer grounded in the actual diff data.

Features

• Semantic commit search — find commits by intent, not keywords
• Incremental indexing — only new commits are re-embedded on each launch
• Full diff awareness — the agent has access to the complete unified diff for each commit
• Cited answers — every factual claim is backed by a [abc1234] commit reference
• Safe by default — destructive git operations (checkout, reset, revert) require explicit confirmation before execution

File structure

GitLensAI/
├── main.py          # Entry point: builds the agent graph and runs the REPL
├── agent.py         # LangGraph node functions and AgentState definition
├── retrieval.py     # FAISS index initialisation, incremental update logic, retriever tool
├── commits.py       # git log parsing → LangChain Documents
├── prompts.py       # System prompt for the LLM agent
├── pyproject.toml   # Project metadata and dependencies (managed by uv)
├── uv.lock          # Locked dependency versions
└── .GitLensAI/      # Auto-generated — FAISS index files and metadata.json

Setup

Prerequisites

• Python 3.13.7+
• uv — Python package and project manager
• An Anthropic API key — not required if you run the chat model locally via Ollama
• A Voyage AI API key — always required (commit embeddings use Voyage AI)

Install

git clone https://github.com/RishabSA/GitLensAI.git
cd GitLensAI

uv sync

Environment variables

Create a .env file in the project root:

ANTHROPIC_API_KEY=your_anthropic_key
VOYAGE_API_KEY=your_voyage_key

Usage

Run from the root of any Git repository you want to query:

# Query the current repository
uv run main.py

# Or point it at a different repo by modifying repo_path in main.py

By default the chat model is anthropic:claude-haiku-4-5. Override it with --model and --temperature:

uv run main.py --model anthropic:claude-haiku-4-5 --temperature 0.1

Using a local model via Ollama

You can run the chat model fully locally with Ollama — no Anthropic API key needed. (Commit embeddings still use Voyage AI, so VOYAGE_API_KEY is still required.)

ollama pull llama3.1
uv run main.py --model ollama:llama3.1

The model must support tool calling. GitLens AI is a retrieval agent — it only answers grounded in commit data by calling a retriever tool. Models without function-calling support (e.g. base llama2 or small models) won't crash, but they'll silently skip retrieval and answer from prior knowledge. Use a tool-capable model such as llama3.1, qwen2.5, or mistral-nemo.

On first launch the index is built (this takes a moment depending on repo size). Subsequent launches load the existing index and only embed new commits.

Loading commits from repository...
Found 47 commits (latest: 366020c)
No existing index — embedding 47 commits...
Index built and saved (head: 366020c)

Ask about your repository history (or type 'exit' to quit): when was the FAISS integration added?

[ea7bacc] — 2025-01-10
The FAISS index was introduced in commit [ea7bacc] ("Full langgraph setup, FAISS + Voyage Vector DB
added"). The diff shows langchain_community.vectorstores.FAISS being imported and wired up alongside
VoyageAIEmbeddings for document embedding and similarity search.

Type exit to quit.