# Rag For Git

> AI pull-request reviewer: hybrid RAG + a code graph + Claude Code. Whole-repo context, inline GitHub comments grounded on exact code. MCP server + Claude Code plugin.

- **Type:** MCP server
- **Install:** `agentstack add mcp-mimfort-rag-for-git`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mimfort](https://agentstack.voostack.com/s/mimfort)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mimfort](https://github.com/mimfort)
- **Source:** https://github.com/mimfort/rag_for_git

## Install

```sh
agentstack add mcp-mimfort-rag-for-git
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# rag_for_git

> **An AI pull-request reviewer that reads your whole repository — hybrid RAG + a code graph + Claude Code.**
> Plain linters check a diff in isolation; this agent gives the model the same context a human
> reviewer has — semantic + lexical retrieval over the entire repo and a structural code graph —
> then posts the result back to GitHub as **inline comments on the exact diff lines, with applyable fixes**.

[](https://pypi.org/project/rag-reviewer/)
[](https://pypi.org/project/rag-reviewer/)
[](LICENSE)
[](#mcp-tools-reference)
[](#claude-code-plugin-marketplace)

> 🇷🇺 Русская версия — глубокий, сверенный с кодом разбор: [README.ru.md](README.ru.md)

---

## Table of contents

- [Why it exists](#why-it-exists)
- [What a review looks like](#what-a-review-looks-like)
- [Highlights](#highlights)
- [How a review runs](#how-a-review-runs)
- [How it works / Architecture](#how-it-works--architecture)
- [One-click install prompt](#one-click-install-prompt)
- [Installation](#installation)
- [Configuration reference](#configuration-reference)
- [CLI reference](#cli-reference)
- [Skills reference](#skills-reference)
- [MCP tools reference](#mcp-tools-reference)
- [Plugin usage](#plugin-usage)
- [Per-repo policy & task board](#per-repo-policy--task-board)
- [Observability web admin](#observability-web-admin)
- [Known limitations & caveats](#known-limitations--caveats)
- [Tests](#tests)
- [Project layout](#project-layout)
- [Contributing](#contributing)
- [License](#license)

---

## Why it exists

Plain linters catch syntax and style but miss **meaning and relationships** — the things a human
reviewer actually looks for:

- a changed function contract that silently breaks its callers,
- a guard clause removed three files away from where it mattered,
- a change that contradicts an existing test,
- an edge case that only shows up once you read the helper it calls.

Catching those needs **context beyond the diff**: who calls this, what it implements, which tests
pin its behaviour. `rag_for_git` gives the model that context — semantic + lexical retrieval over
the **whole repository** and a structural **code graph** — then runs an agentic tool loop per
changed file and posts the result back to GitHub as **inline comments on the exact diff lines,
plus a summary and applyable fixes**.

It is not a wrapper around "send the diff to an LLM." It is a retrieval + code-graph pipeline with
a deterministic, anti-hallucination publishing tail.

## What a review looks like

An *illustrative* inline comment the agent posts on a changed line — it found the bug by following
the call graph from the edited function to its callers and a contract test:

> **🟠 correctness — an expired token is no longer rejected**
>
> `verify_token` used to raise on an expired signature; the new guard only checks `payload is
> None`, so `_decode()` returning a payload with a past `exp` now passes as valid. Two call sites
> depend on that raise — `require_auth` (`auth/deps.py:48`) and the contract test
> `test_expired_rejected` (`tests/test_auth.py:71`), which this change would break.
>
> ```suggestion
>     if payload is None or payload.get("exp", 0)          raise InvalidToken("expired or malformed token")
> ```
> 

Every finding is grounded on an **exact quote** from the diff, carries a category / severity /
confidence, and — when it's safe — ships as a one-click GitHub `suggestion`. A hidden fingerprint
(``) makes re-runs **idempotent**: the same issue is never posted twice.

## Highlights

- **Whole-repo context, not just the diff.** Hybrid retrieval (pgvector ANN + BM25, fused with RRF,
  reranked by Voyage) over the entire indexed codebase — for changed files the agent sees the new
  version, for everything else a stable base index.
- **It sees impact.** A Neo4j code graph (`CALLS` / `IMPLEMENTS`) expands each changed symbol 1–2
  hops to surface callers, callees, implementations, and the tests that pin them.
- **Anti-hallucination by construction.** A finding must quote real code to be placed on a line; a
  dedicated **verify** pass drops invented findings; line grounding is exact-match.
- **Real GitHub output.** Inline comments on diff lines, applyable `suggestion` blocks under safe
  invariants, a summary for everything off-diff — idempotent across re-runs.
- **Lives in your editor, not a CI black box.** Ships as a **Claude Code plugin** and as an **MCP
  server** usable from 12+ AI clients (Cursor, VS Code, Gemini CLI, Codex, Windsurf, Claude
  Desktop, …). One `uvx` command; published on [PyPI](https://pypi.org/project/rag-reviewer/).
- **Local-first.** Your code stays on your machine — only embedding/query text goes to Voyage; the
  stores (Postgres/ParadeDB + Neo4j) run in local Docker.
- **More than review.** The same RAG + graph powers grounded codebase **Q&A** (`ask`), PR
  **walkthroughs**, and per-subsystem summaries.
- **From task to implementation — the killer feature.** `solve-task` reads a task from your board,
  pulls related tasks/prs/code via the RAG + graph, distills a structured brief, and hands off to the
  **full superpowers cycle**: brainstorming → writing-plans → subagent-driven-development →
  executing-plans → finishing. The only end-to-end pipeline that truly connects your task tracker
  to implementation.

## How a review runs

A single PR review is three stages:

**`prepare_review` (MCP)** → **analyze (Claude subagents)** → **`publish_review` (MCP)**

1. **prepare** — `GitHubProvider` pulls the PR (base/head SHA) and changed files; changed `.py`
   files are chunked (tree-sitter) and embedded (Voyage) into an ephemeral overlay `ref="pr:N"`;
   policy and per-file review units are assembled.
2. **analyze** — the Claude Code skill fans out one subagent per file. Each reasons over the diff
   in a tool loop, pulling in whatever code it needs: `search_code`, `get_related_symbols`,
   `read_file`, `get_definition`, `find_callers`, `get_changed_file_diff`. In parallel,
   dimension subagents run a **performance** and **maintainability** pass, plus a **requirements**
   pass when a task board is wired up, and a final **verify** pass strips hallucinations.
3. **publish** — a deterministic tail: policy gate (category/severity/confidence/paths) → line
   grounding by exact code quote (anti-hallucination) → dedup → assemble (inline vs summary,
   suggestion invariants, fingerprint idempotency, comment cap) → post to GitHub → history record
   → overlay/session cleanup.

> Status: working v1. Target analysis language is **Python**; VCS is **GitHub** (behind a
> `VCSProvider` interface). Proven live: it catches real bugs and sees the impact on calling code
> and existing tests.

## How it works / Architecture

The core is the `reviewer/` library, assembled in `reviewer/app.py::build_components(settings)`
from `Settings` (pydantic-settings, `.env`). Entry points are `reviewer/entrypoints/cli.py` (Click)
and `reviewer/entrypoints/mcp_server.py` (FastMCP). Three pieces work together:

- **RAG (hybrid retrieval).** Postgres/ParadeDB stores code chunks with `pgvector` (HNSW ANN) and
  `pg_search` (BM25). A query embeds with Voyage, runs both ANN and BM25 search, and the result
  lists are merged with **Reciprocal Rank Fusion (RRF)**, then reranked with Voyage `rerank-2.5`.
- **Code graph (SCIP or tree-sitter, Neo4j).** Symbols and their relationships live in Neo4j.
  The graph orchestrator (`graph/backend.py`) picks a backend via `GRAPH_BACKEND`
  (`auto|scip|treesitter`): **SCIP** (`@sourcegraph/scip-python`) gives a precise, type-aware graph
  with `CALLS` + `IMPLEMENTS` edges; **tree-sitter** is a fast fallback with `CALLS`-by-name only.
  Retrieval expands the changed symbols 1–2 hops to surface callers/callees/implementations/tests.
- **Claude Code plugin via MCP.** The `reviewer-mcp` server exposes `prepare_review`,
  `publish_review`, and the agent tools. The Claude Code plugin (`plugin/`) drives the review: it
  calls `prepare_review`, runs analysis subagents against those MCP tools, then calls
  `publish_review`.

**The single key linking RAG and the graph is `node_id = "path#fqn"`** (e.g.
`rag/embedder.py#VoyageEmbedder.embed_query`). Both the chunk in Postgres and the node in Neo4j use
it, so graph expansion and chunk retrieval are stitched together without any mapping table.

**Index freshness: a stable base + a PR overlay.** A full reindex of a large repo is expensive, so
the index keeps a persistent base and layers PR changes on top:

- **`ref="base:"`** — the persistent index of a tracked branch (e.g. `"base:main"`,
  `"base:master"`). Each tracked branch in `REVIEW_BRANCHES` has its own isolated index. Updated
  incrementally by `reviewer index --ref ` (only changed files are chunked; only chunks
  with a new `content_hash` are re-embedded — embeddings are reused across branches by hash,
  saving Voyage quota).
- **`ref="pr:N"`** — an ephemeral overlay of just the PR's changed files at its HEAD.
- **On a query**: `retrieval = (base: where path ∉ changed) ∪ overlay`. For changed files
  the agent sees the **new** version; for everything else, the stable base.
- **Multi-branch.** A PR is reviewed against the index of its target branch (`base_ref` from the
  PR). A PR targeting an untracked branch is skipped (`prepare_review` returns
  `{"status":"skipped",...}`). The code graph (Neo4j `:Symbol`) is also branch-scoped via a
  `branch` property, with unique constraint `(repo, branch, id)`.

```
                ┌─────────────────────────── reviewer (core library) ───────────────────────────┐
                │                                                                                 │
  GitHub PR ───▶│  VCSProvider (github.py)  ──diff/files/patches──▶  MCPReviewService             │
  (owner/repo#N)│        ▲  publish inline + summary                       │ prepare_review        │
                │        │                                                 ▼                       │
                │        │                          ┌──────────── retrieval/Retriever ──────────┐ │
                │        │                          │  hybrid search        graph expansion      │ │
                │        │                          │  ┌──────────────┐   ┌───────────────────┐  │ │
                │        │                          │  │ Postgres      │   │ Neo4j             │  │ │
                │        │                          │  │ (ParadeDB)    │   │ Symbol(path#fqn)  │  │ │
                │        │                          │  │ pgvector(HNSW)│   │ -[:CALLS]->        │  │ │
                │        │                          │  │ + pg_search   │   │ (IMPLEMENTS: SCIP) │  │ │
                │        │                          │  │   (BM25, RRF) │   │ expand 1–2 hops    │  │ │
                │        │                          │  └──────┬───────┘   └─────────┬─────────┘  │ │
                │        │                          │   Voyage embed/rerank   tree-sitter graph  │ │
                │        │                          └─────────────────┬─────────────────────────┘ │
                │        │                                            ▼ ContextPack                │
                │        │                       Claude Code subagents (skill /rag-reviewer:reviewer_review-pr)
                │        │                         tools: search_code, get_related_symbols,        │
                │        │                         read_file, get_definition, find_callers, …      │
                │        └─────────────────── publish_review (gate/grounding/dedup/assemble) ◀─────┘
                └─────────────────────────────────────────────────────────────────────────────────┘

  Stores (Docker):  Postgres/ParadeDB (:5433)  ·  Neo4j (:7687)
  External API:     Voyage (embeddings voyage-code-3 + reranker rerank-2.5)
```

For a deeper, code-verified walkthrough of every module and the data flow, see
[README.ru.md](README.ru.md) (Russian).

## One-click install prompt

Copy and paste into any AI coding assistant:

```
uvx --from rag-reviewer reviewer install --all
```

This auto-detects installed AI clients and wires the MCP server. For manual setup see [Manual setup](#manual-setup-alternative) below.

---

## Installation

The MCP server is published on PyPI as [`rag-reviewer`](https://pypi.org/project/rag-reviewer/)
and runs via `uvx` — **no clone of this repo required**.

Requirements: Docker, [`uv`](https://docs.astral.sh/uv/getting-started/installation/) (includes `uvx`),
a Voyage API key, a GitHub token. Python 3.11–3.13 (only needed for a `pip`/editable install; `uvx`
manages its own).

### Quick setup (recommended, all platforms)

```bash
# 0) Install the reviewer CLI — once, globally
uv tool install rag-reviewer
# uv and uvx are the same binary; installing uv gives you both.
# The MCP server launched by your editor uses uvx @latest and self-updates automatically.

# 1) Infrastructure
curl -O https://raw.githubusercontent.com/mimfort/rag_for_git/main/docker-compose.yml
docker compose up -d          # Postgres/ParadeDB (:5433) + Neo4j (:7687)

# 2) Configure keys and settings interactively
reviewer init
#    Interactive wizard: fills VOYAGE_API_KEY, GITHUB_TOKEN, and optional groups
#    (stores, multi-repo, task board). Re-run any time to update settings.
#    CI / non-interactive: reviewer init --yes  (accepts all defaults silently)

# 3) Register the MCP server (and skills) in your editor/CLI
reviewer install --all        # auto-detect installed clients + install skills
#    or a specific one: reviewer install cursor|vscode|claude-code|claude-desktop|windsurf|gemini|antigravity|mimo|opencode|kimi|trae|codex
#    skills go to clients that support them (Gemini/Mimo/Kimi); add --no-skills to skip

# 4) Verify
reviewer check

# Update CLI later:
uv tool upgrade rag-reviewer
```

> **`reviewer install` is cross-platform** (Windows / macOS / Linux). It injects the
> absolute path to `uvx` automatically — no `bash -lc` wrapper needed. The manual
> JSON configs below use `bash -lc` for macOS/Linux only; on Windows use
> `reviewer install` or set `"command": "uvx"` with `"args": ["--from",
> "rag-reviewer@latest", "reviewer-mcp"]` directly.

> **Claude Code: tools work out of the box.** `reviewer install claude-code` also
> writes an allowlist rule `mcp__reviewer__*` into your global
> `~/.claude/settings.json` (`permissions.allow`), so the reviewer MCP tools run in
> **every** project without hitting the `auto`-mode safety classifier — no manual
> settings edits. Being global, it also covers the plugin (marketplace) install,
> where the server is available everywhere but ships no permission grants.

> **Where keys are read from.** The reviewer resolves its `.env` from a fixed
> location, **not** the current working directory — MCP clients launch the server
> with an arbitrary CWD, so a project-local `.env` is unreliable. Lookup order:
> `$REVIEWER_ENV_FILE` → `$XDG_CONFIG_HOME/rag-reviewer/.env` (default
> `~/.config/rag-reviewer/.env`) → `./.env` (handy when running from a repo clone).
> Real environment variables always win over the file, so you can instead pass keys
> via an `"env": { "VOYAGE_API_KEY": "…", "GITHUB_TOKEN": "…" }` block in your MCP
> client config — works in every client.

- **Voyage** (`VOYAGE_API_KEY`): https://dashboard.voyageai.com/ — free token pool; attach a card
  to lift the 3 RPM / 10K TPM limit (charged only beyond the free pool).
- **GitHub** (`GITHUB_TOKEN`): a PAT with *Pull requests: Read and write* + *Contents: Read*
  (fine-grained) or the `repo` scope (classic). Quick option: `gh auth token`.

All other settings have defaults (documented in `.env.example` and in
[Configuration reference](#configuration-reference) below).

### Manual setup (alternative)

If you prefer to configure your client config by hand rather than using `reviewer install`:

Each AI coding tool has its own config file. Pick yours:

| Tool | Global config file | Project config | Install

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [mimfort](https://github.com/mimfort)
- **Source:** [mimfort/rag_for_git](https://github.com/mimfort/rag_for_git)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mimfort-rag-for-git
- Seller: https://agentstack.voostack.com/s/mimfort
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.