Rag For Git

ragforgit

> 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.

• 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.

1. 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.

1. 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 and runs via uvx — no clone of this repo required.

Requirements: Docker, uv (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)

# 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
• Source: mimfort/ragfor_git
• License: MIT

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