rag-rat

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

# 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__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:

  [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 — in Claude Code run /mcp and reconnect rag-rat; in Codex and opencode, start a new session.

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

Manual installation and other agents

Use this path for the standalone CLI, agents without plugin support, or building from source.

Install the CLI

The prebuilt package needs no Rust toolchain and supports Apple Silicon macOS, glibc ≥2.38 Linux (x86-64 and arm64), Windows x64, and Android/Termux arm64:

npm install -g @rag-rat/bin

or run it without installing:

npx @rag-rat/bin --help

@rag-rat/bin fetches the full binary from the matching GitHub release. FastEmbed's ONNX Runtime is statically linked.

To build from source instead:

cargo install rag-rat

or from a checkout:

cargo install --path crates/rag-rat-cli --bin rag-rat

The default source build needs glibc ≥2.38 and is unavailable for Intel macOS and musl/Alpine. On those platforms, including Ubuntu 22.04, use the pure-Rust embedder:

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

--no-default-features alone produces a smaller hash-only build without real embeddings. SQLite is bundled; see Platform support for toolchain details.

Initialize the repository

cd /path/to/your/repo

rag-rat init

init is an interactive terminal wizard: it scans the repo, guides language and embedding choices, writes rag-rat.toml, and builds the initial index. For a non-interactive setup use rag-rat init --yes, which takes the defaults and installs the git maintenance hooks (add --no-hooks to skip them; --dry-run previews the config without writing). --yes never replaces an existing rag-rat.toml unless you add --force — rerun the wizard to reconfigure instead. Configuration reference: docs/config.md.

Add skills and connect MCP

Install the skills for Claude Code, Codex, Cursor, and 70+ other detected agents:

npx @rag-rat/skills

That installs using-rag-rat, dream-review, init-rag-rat, and configure-rag-rat-dream. See skills/README.md for per-agent flags and update, list, and remove.

The MCP server uses STDIO: the client launches rag-rat mcp from the repository so it discovers the correct rag-rat.toml and repository scope in the consolidated machine-global store.

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

codex mcp add rag-rat -- rag-rat mcp

Or add the equivalent project configuration:

{

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

rag-rat init prints the registration command but does not register the server itself. Pass rag-rat mcp --json if the client must parse JSON; tool text defaults to TOON. Full tool schemas: docs/mcp-tools.md.

Claude Code tool permissions

Claude Code asks once before each rag-rat MCP tool first runs. Choose "Yes, don't ask again," or allow the tool namespace in ~/.claude/settings.json:

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

Do not pin a global server to one repository's config. A user-scoped server with

--config /some/repo/rag-rat.toml serves that repository everywhere. Register MCP per project and

let the process discover the config from its working directory.

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:

• "Run impact_surface on the function I'm about to edit — its callers, callees, tests, and recent commits."
• "Where is config reload handled?" — hybrid semantic_search over source and docs.
• "What are the most load-bearing symbols in this repo?" — important_symbols.
• "Does this helper duplicate anything already in the codebase?" — find_clones (and the write-time hook warns as you write it).
• "Record an invariant on parse_config: reload must not allocate after the scheduler starts." — memory_create writes your first repo memory; it then rides along in future impact_surface / symbol_lookup results.

Or from the CLI:

rag-rat query "where is config reload handled?"

rag-rat important-symbols --limit 20 rag-rat brief --mode spine rag-rat clusters --limit 10 rag-rat tools impact-surface --symbol parse_config

The agent loop

The point isn't the tool catalog — it's the loop an agent runs *around* an edit, so it changes code with the callers, tests, rationale, and prior art in front of it instead of guessing:

1. Before editing a symbol, ask `impact_surface`. One call returns the current source anchor, callers and callees, related tests, git/GitHub rationale, the repo memories bound to that symbol / path / call-path, and confidence + coverage warnings.
2. Read the blast radius, then edit. The invariant a previous agent recorded, the caller three hops away, the test that pins the behavior — all surfaced before the change, not discovered after.
3. The clone hook catches duplication at write time. If the new function reimplements code that already exists, the Write/Edit hook says so, with the ex