rag-rat

# rag-rat

[![CI](https://github.com/cq27-dev/rag-rat/actions/workflows/ci.yml/badge.svg)](https://github.com/cq27-dev/rag-rat/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/cq27-dev/rag-rat/branch/main/graph/badge.svg)](https://codecov.io/gh/cq27-dev/rag-rat)
[![crates.io](https://img.shields.io/crates/v/rag-rat.svg)](https://crates.io/crates/rag-rat)
[![benchmarks](https://img.shields.io/badge/benchmarks-bencher-orange)](https://bencher.dev/perf/rag-rat/plots)
[![site](https://img.shields.io/badge/site-rag--rat.cq27.dev-2563eb)](https://rag-rat.cq27.dev)

**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](https://rag-rat-demo.cq27.dev/?folder=/srv/workspace&payload=%5B%5B%22gotoLineMode%22%2C%22true%22%5D%2C%5B%22openFile%22%2C%22vscode-remote%3A//rag-rat-demo.cq27.dev/srv/workspace/crates/rag-rat-oplog/src/account/content/storage.rs%3A1459%3A1%22%5D%5D) — 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.

```mermaid
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](docs/oracle.md) 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](docs/distillation.md) — 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](docs/grep-augmentation.md) 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`):

```bash
# 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
  [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](#try-it).

<details>
<summary><strong>Manual installation and other agents</strong></summary>

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:

```bash
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:

```bash
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:

```bash
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](#platform-support) for toolchain details.

### Initialize the repository

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

`init` scans the repo, guides language and embedding choices, writes `rag-rat.toml`, and builds the
initial index. Use `rag-rat init --dry-run` to preview without writing, or `--yes` for
non-interactive defaults. Configuration reference: [`docs/config.md`](docs/config.md).

### Add skills and connect MCP

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

```bash
npx @rag-rat/skills
```

That installs `using-rag-rat`, `dream-review`, `init-rag-rat`, and
`configure-rag-rat-dream`. See [`skills/README.md`](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.

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

Or add the equivalent project configuration:

```json
{
  "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](#output). Full tool
schemas: [`docs/mcp-tools.md`](docs/mcp-tools.md).

<details>
<summary>Claude Code tool permissions</summary>

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

```json
{ "permissions": { "allow": ["mcp__rag-rat__*"] } }
```
</details>

> **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.

</details>

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