rag-rat is a local codebase intelligent indexing and MCP server that serves programming agents. It works under the premise that source files are read-only, writes only to its own SQLite database, and attaches provenance to every returned result. Its goal is to connect the code an agent is about to modify with its callers, callees, tests, git/GitHub history, past decisions, invariants, risks, and duplicate-code signals, and to annotate each result with confidence and coverage so the agent can judge for itself.
Purpose
rag-rat is intended to supplement the grep and file-reading capabilities that programming agents already have, providing a layer they lack: source-anchored rationale. It is aimed at coding agents working in an editor or on the command line, helping them understand the scope of impact and historical decisions before modifying code.
Main capabilities
- Provenance rather than guesswork: every result carries confidence labels, coverage warnings, and raw evidence; partial indexes or ambiguous edges are presented as they are.
- Repo memories: typed, source-anchored notes (such as Invariant, Decision, Risk, etc.) that survive refactoring and automatically surface in subsequent queries. They are versioned, local, source-anchored facts about the repository, not assistant memory.
- Real code graph: caller/callee/import relationships for Rust, TypeScript/TSX, Kotlin, C/C++, Python, Swift, and Go via tree-sitter; an optional compiler-level SCIP oracle for configured toolchains upgrades edges to Compiler confidence and ranks key symbols.
- History as evidence: git history, lazy chunk blame, and cached GitHub issue/PR/review rationale are all queryable.
- Issue distillation: each closed issue and merged PR along with its fix diff is distilled into a typed decision record containing the root cause, the approach ultimately adopted (and rejected alternatives), and the outcome, anchored to the relevant symbols and surfaced as context.
- Enhancing existing grep: the grep enhancement hook injects the memories and symbols behind what you just searched for into the results.
- Detecting clones while writing: for Write/Edit/MultiEdit's PreToolUse hook fingerprints the function you are writing and warns when it is identical or near-duplicate to code already in the repository. The hook is read-only, silently no-ops when the index is not ready, and does not block writes.
How to use
For Claude Code, Codex, and opencode, you can install a plugin: it registers the MCP server, adds hooks, and on first run fetches the version-matched rag-rat binary, which the MCP server exposes at startup as ~/.local/bin/rag-rat (the Claude Code and Codex packages also add skills; for opencode you can add them with npx @rag-rat/skills).
After installation you need to approve the plugin so that its tools and hooks run. Claude Code asks the first time each rag-rat MCP tool runs, where you can choose "Yes, don't ask again", or pre-allow it in ~/.claude/settings.json. Codex shows a "Hooks need review" prompt in the first session started within the repository; choose "Trust all and continue" to enable it. For unattended commands (such as codex review), you can allow the plugin's MCP tools in ~/.codex/config.toml, then restart Codex.
There is also a standalone CLI path, for agents without plugin support or when building from source. Prebuilt packages require no Rust toolchain and support Apple Silicon macOS, Linux with glibc >=2.38 (x86-64 and arm64), Windows x64, and Android/Termux arm64. @rag-rat/bin fetches the full binary from the corresponding GitHub release, and FastEmbed's ONNX Runtime is statically linked. When building from source, the default build requires glibc >=2.38 and does not support Intel macOS or musl/Alpine; on these platforms (including Ubuntu 22.04) you should use the pure Rust embedder.
To initialize a repository use init (an interactive terminal wizard that scans the repository, derives language and embedding choices, writes rag-rat.toml, and builds the initial index). For non-interactive use, rag-rat init --yes adopts the defaults and installs the git maintenance hooks (--no-hooks skips this; --dry-run previews the configuration). --yes will not overwrite an existing rag-rat.toml unless you add --force. For the configuration reference see docs/config.md.
The MCP server uses STDIO: the client starts rag-rat mcp from the repository in order to discover the correct rag-rat.toml and repository scope. rag-rat init prints the registration command but does not register itself. You can pass rag-rat mcp --json to have the client parse JSON; tool text is TOON by default. For the full tool schema see docs/mcp-tools.md. Note that you should not pin a global server to a single repository's configuration; register MCP per project so that the process discovers the configuration from the working directory.
Once the repository is indexed, the code graph, symbols, git history, semantic search, and clone detection become available; repository memory starts out empty and accumulates as the agent records findings with memory_create, and it automatically surfaces in subsequent results (issue/PR rationale requires rag-rat papertrail sync).
Common tools include: impact_surface (coding preflight: callers, callees, tests, git history, GitHub papertrail, and repository memory across symbols), semantic_search (hybrid BM25 + vector recall over source code and docs), symbol_lookup, find_callers / trace_callees, important_symbols, find_clones, memory_create, and others. Maintenance and diagnostic tools such as dream, heal_index, memory_doctor, and others are in the optional admin and graph toolsets ([mcp] toolsets). See docs/mcp-tools.md for all tools.
Repository memory is a typed graph rather than a flat list: memory_edge_add / memory_edges use depends_on, relates_to, superseRelations such as des, derived_from, and tracks connect them. dream is the maintenance loop that keeps the memory layer reliable, recomputing a sorted work list about memory itself (such as coverage gaps and stale references), with each entry having a stable id for review.
Applicable scenarios
Suitable for teams or individual developers who use coding agents for development and want to grasp the scope of impact, tests, historical decisions, and duplicate code signals before modifying code. Applicable to MCP-supporting clients (such as Claude Code, Codex, opencode) as well as integration methods via CLI or source builds.
Limitations
The materials provided by the repository do not clearly state pricing, charging models, performance benchmarks, or specific constraints; this information is not currently available. Regarding platform support, the default source build does not support Intel macOS and musl/Alpine; these platforms require the pure Rust embedder.
