cq27-dev/rag-rat

**What a repository knows about itself.** rag-rat is a local repo-intelligence index and MCP server
for coding agents. It keeps source files read-only, writes only its own SQLite database, and answers
with provenance on every result — current source, the code graph, git/GitHub history, and durable,
source-anchored repo memories that persist across sessions and agents.
Explore the live VS Code Lens demo — no installation required.
It surfaces clone classes, repo memories, and issue/decision context alongside the code; press
Ctrl+Alt+R to reveal clone overlays.
Every coding harness already has grep and file reads. rag-rat adds the layer they do not provide:
source-anchored *rationale*. It connects the code an agent is about to touch to its callers, callees,
tests, git/GitHub history, prior decisions, invariants, risks, and duplicate-code signals — and
labels every result with confidence and coverage, so an agent can judge it instead of trusting it.
Why
- **Provenance, not guesses.** Every result carries a confidence label, coverage warnings, and the
raw evidence — so a partial index or an ambiguous edge reads as exactly that.
- **Repo memories.** Typed, source-anchored notes (Invariant, Decision, Risk, …) that survive
refactors and surface automatically during future queries — the signal grep can't give you. They
are *not* assistant memory: they are versioned, local, source-anchored facts about **this**
repository that any future agent retrieves with evidence.
- **A real code graph.** tree-sitter callers/callees/imports across Rust, TypeScript/TSX, Kotlin,
C/C++, Python, Swift, and Go — with an optional compiler-grade SCIP oracle for
configured toolchains that upgrades edges to Compiler confidence and ranks the load-bearing
symbols.
- **History as evidence.** Git history, lazy chunk blame, and cached GitHub issue/PR/review
rationale, all queryable.
- **Issue distillation.** Every closed issue and merged PR **plus its fixing diff** distilled into a typed
decision record — root cause, the approach that landed (and the rejected
alternatives), and the outcome — validated against the thread and surfaced as drive-by context on
the anchored symbols.
- **Rides your existing grep.** A grep-augmentation hook injects the
memories and symbols behind whatever you just searched for.
- **Flags clones as you write them.** A PreToolUse hook on Write/Edit/MultiEdit fingerprints the
functions you're writing and warns when they're exact or near-duplicates of code already in the
repo — so an agent reuses instead of re-implementing. Read-only, and a silent no-op when the index
isn't ready, so it never blocks a write.
Quickstart
For Claude Code, Codex, and opencode, install the plugin. It registers the MCP server, adds the
hooks, and fetches a version-matched rag-rat binary on first run, which the MCP server exposes as
~/.local/bin/rag-rat when it starts — see Running the CLI (the Claude Code and
Codex bundles also add the skills; on opencode add them with npx @rag-rat/skills):
After installing, approve the plugin so its tools and hooks run (opencode loads plugins without an
approval step — nothing to do there):
- **Claude Code** asks before each rag-rat MCP tool the first time it runs — choose "Yes, don't ask
again," or pre-allow them in ~/.claude/settings.json with
"permissions": { "allow": ["mcp__plugin_rag-rat_rag-rat__*"] } (plugin tools are named
mcp__plugin_rag-rat_rag-rat__ ; a server added by hand with claude mcp add uses
mcp__rag-rat__* instead).
- **Codex** shows a **"Hooks need review"** prompt on the first codex session started *inside the
repo* (the plugin ships grep-augmentation, clone-check, and session-digest hooks that run outside
the sandbox). Choose **"Trust all and continue"** to enable them. For unattended commands such as
codex review, also allow the plugin's MCP tools in ~/.codex/config.toml so the run cannot stall
on a per-tool approval prompt:
This trusts every current and future MCP tool exposed by the installed rag-rat plugin. Only enable
it when you trust the plugin's source and installation origin, then restart Codex.
Then open the repository and ask:
> Set up rag-rat in this repo.
The init-rag-rat skill scans the repo, explains the material choices, previews rag-rat.toml,
writes and indexes only after confirmation, and offers to set up the git hooks that keep the index
fresh. The MCP server starts dormant in an unconfigured repo; when setup finishes, reconnect it so it
restarts fully active against the new index — in Claude Code run /mcp and reconnect rag-rat; in