rag-rat
About
Provides local repo-intelligence by indexing source, symbols, call graphs, Git/GitHub history, and source-bound repo memories into a local database for coding agents.
Details
- Author
- cq27-dev
- Categories
- AI, Developer Tools, Knowledge Base, Other
Jump to
Setup
Install rag-rat in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/cq27-dev/rag-rat
Follow the installation instructions in the repository README, then restart your MCP client.
What a repository knows about itself.rag-ratis 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.
Every coding harness already hasgrepand file reads. rag-rat adds the layer they do not provide: source-anchoredrationale. 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
- 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 arenotassistant memory: they are versioned, local, source-anchored facts aboutthisrepository 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 optionalcompiler-grade SCIP oraclefor configured toolchains that upgrades edges toCompilerconfidence 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 PRplus its fixing diffdistilled into a typeddecision 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.Agrep-augmentation hookinjects 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.
For Claude Code, Codex, and opencode, install the plugin. It registers the MCP server, adds the hooks, and installs a version-matchedrag-ratbinary on first run (the Claude Code and Codex bundles also add the skills; on opencode add them withnpx @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 Codeasks before each rag-rat MCP tool the first time it runs — choose "Yes, don't ask again," or pre-allow them in~/.claude/settings.jsonwith"permissions": { "allow": ["mcp__rag-rat__"] }.
Codexshows a"Hooks need review"prompt on the firstcodexsession startedinside 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 ascodex review, also allow the plugin's MCP tools in~/.codex/config.tomlso 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.
Theinit-rag-ratskill scans the repo, explains the material choices, previewsrag-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 inTry it.
Use this path for the standalone CLI, agents without plugin support, or building from source.
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/binfetches the full binary from the matching GitHub release. FastEmbed's ONNX Runtime is statically linked.
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-featuresalone produces a smaller hash-only build without real embeddings. SQLite is bundled; seePlatform supportfor toolchain details.
initscans the repo, guides language and embedding choices, writesrag-rat.toml, and builds the initial index. Userag-rat init --dry-runto preview without writing, or--yesfor non-interactive defaults. Configuration reference:docs/config.md.
Install the skills for Claude Code, Codex, Cursor, and 70+ other detected agents:
That installsusing-rag-rat,dream-review,init-rag-rat, andconfigure-rag-rat-dream. Seeskills/README.mdfor per-agent flags andupdate,list, andremove.
The MCP server uses STDIO: the client launchesrag-rat mcpfrom the repository so it discovers the correctrag-rat.tomland 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 initprints the registration command but does not register the server itself. Passrag-rat mcp --jsonif the client must parse JSON; tool text defaults toTOON. Full tool schemas:[docs/mcp-tools.md.
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:
…
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
