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.

sequenceDiagram
    participant Repo as Repository
    participant Engine as rag-rat engine
    participant Agent as Coding agent

    Repo->>Engine: Source · git/GitHub · repo memories
    Engine->>Engine: Index → graph → (opt) SCIP oracle → reconcile
    Agent->>Engine: where / why / who-calls / impact?
    Engine-->>Agent: source + call paths + papertrail + memories (with provenance)
    Agent->>Engine: record a finding
    Engine->>Repo: persist a source-anchored repo memory

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 installs a version-matched rag-rat binary on first run (the Claude Code and Codex bundles also add the skills; on opencode add them with npx @rag-rat/skills):

# Claude Code
claude plugin marketplace add cq27-dev/rag-rat
claude plugin install rag-rat@rag-rat

# Codex
codex plugin marketplace add cq27-dev/rag-rat
codex plugin add rag-rat@rag-rat

# opencode (add -g for a global install)
opencode plugin @rag-rat/plugin-opencode

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__rag-rat__*"] }.

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

  toml

  Copy

  [plugins."rag-rat@rag-rat".mcp_servers.rag-rat]
  default_tools_approval_mode = "approve"
  

  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.

Then put it to work — the loop rag-rat is built for is in Try it.

npm install -g @rag-rat/bin
# or run it without installing:
npx @rag-rat/bin --help

cargo install rag-rat
# or from a checkout:
cargo install --path crates/rag-rat-cli --bin rag-rat

cargo install rag-rat --no-default-features --features model2vec

cd /path/to/your/repo
rag-rat init

npx @rag-rat/skills

claude mcp add --scope project rag-rat -- rag-rat mcp
codex  mcp add rag-rat -- rag-rat mcp

{
  "mcpServers": {
    "rag-rat": { "command": "rag-rat", "args": ["mcp"] }
  }
}

{ "permissions": { "allow": ["mcp__rag-rat__*"] } }

Try it

Once the repo is indexed, the code graph, symbols, git history, semantic search, and clone detection are ready — these answer on the first query. Repo memories start empty: they accrue as agents record findings with memory_create and then surface automatically in later answers. (Tracker issue/PR rationale needs a rag-rat papertrail sync.)

Ask your MCP client: