{
"markdown": "# rag-rat\n\n[](https://github.com/cq27-dev/rag-rat/actions/workflows/ci.yml)\n[](https://codecov.io/gh/cq27-dev/rag-rat)\n[](https://crates.io/crates/rag-rat)\n[](https://bencher.dev/perf/rag-rat/plots)\n[](https://rag-rat.cq27.dev)\n\n**What a repository knows about itself.** `rag-rat` is a local repo-intelligence index and MCP server\nfor coding agents. It keeps source files read-only, writes only its own SQLite database, and answers\nwith provenance on every result — current source, the code graph, git/GitHub history, and durable,\nsource-anchored repo memories that persist across sessions and agents.\n\nExplore 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.\nIt surfaces clone classes, repo memories, and issue/decision context alongside the code; press\n`Ctrl+Alt+R` to reveal clone overlays.\n\nEvery coding harness already has `grep` and file reads. rag-rat adds the layer they do not provide:\nsource-anchored *rationale*. It connects the code an agent is about to touch to its callers, callees,\ntests, git/GitHub history, prior decisions, invariants, risks, and duplicate-code signals — and\nlabels every result with confidence and coverage, so an agent can judge it instead of trusting it.\n\n```mermaid\nsequenceDiagram\n participant Repo as Repository\n participant Engine as rag-rat engine\n participant Agent as Coding agent\n\n Repo->>Engine: Source · git/GitHub · repo memories\n Engine->>Engine: Index → graph → (opt) SCIP oracle → reconcile\n Agent->>Engine: where / why / who-calls / impact?\n Engine-->>Agent: source + call paths + papertrail + memories (with provenance)\n Agent->>Engine: record a finding\n Engine->>Repo: persist a source-anchored repo memory\n```\n\n## Why\n\n- **Provenance, not guesses.** Every result carries a confidence label, coverage warnings, and the\n raw evidence — so a partial index or an ambiguous edge reads as exactly that.\n- **Repo memories.** Typed, source-anchored notes (`Invariant`, `Decision`, `Risk`, …) that survive\n refactors and surface automatically during future queries — the signal grep can't give you. They\n are *not* assistant memory: they are versioned, local, source-anchored facts about **this**\n repository that any future agent retrieves with evidence.\n- **A real code graph.** tree-sitter callers/callees/imports across Rust, TypeScript/TSX, Kotlin,\n C/C++, Python, Swift, and Go — with an optional [compiler-grade SCIP oracle](docs/oracle.md) for\n configured toolchains that upgrades edges to `Compiler` confidence and ranks the load-bearing\n symbols.\n- **History as evidence.** Git history, lazy chunk blame, and cached GitHub issue/PR/review\n rationale, all queryable.\n- **Issue distillation.** Every closed issue and merged PR **plus its fixing diff** distilled into a typed\n [decision record](docs/distillation.md) — root cause, the approach that landed (and the rejected\n alternatives), and the outcome — validated against the thread and surfaced as drive-by context on\n the anchored symbols.\n- **Rides your existing grep.** A [grep-augmentation hook](docs/grep-augmentation.md) injects the\n memories and symbols behind whatever you just searched for.\n- **Flags clones as you write them.** A PreToolUse hook on Write/Edit/MultiEdit fingerprints the\n functions you're writing and warns when they're exact or near-duplicates of code already in the\n repo — so an agent reuses instead of re-implementing. Read-only, and a silent no-op when the index\n isn't ready, so it never blocks a write.\n\n## Quickstart\n\nFor Claude Code, Codex, and opencode, install the plugin. It registers the MCP server, adds the\nhooks, and installs a version-matched `rag-rat` binary on first run (the Claude Code and Codex\nbundles also add the skills; on opencode add them with `npx @rag-rat/skills`):\n\n```bash\n# Claude Code\nclaude plugin marketplace add cq27-dev/rag-rat\nclaude plugin install rag-rat@rag-rat\n\n# Codex\ncodex plugin marketplace add cq27-dev/rag-rat\ncodex plugin add rag-rat@rag-rat\n\n# opencode (add -g for a global install)\nopencode plugin @rag-rat/plugin-opencode\n```\n\nAfter installing, approve the plugin so its tools and hooks run (opencode loads plugins without an\napproval step — nothing to do there):\n\n- **Claude Code** asks before each rag-rat MCP tool the first time it runs — choose \"Yes, don't ask\n again,\" or pre-allow them in `~/.claude/settings.json` with\n `\"permissions\": { \"allow\": [\"mcp__rag-rat__*\"] }`.\n- **Codex** shows a **\"Hooks need review\"** prompt on the first `codex` session started *inside the\n repo* (the plugin ships grep-augmentation, clone-check, and session-digest hooks that run outside\n the sandbox). Choose **\"Trust all and continue\"** to enable them. For unattended commands such as\n `codex review`, also allow the plugin's MCP tools in `~/.codex/config.toml` so the run cannot stall\n on a per-tool approval prompt:\n\n ```toml\n [plugins.\"rag-rat@rag-rat\".mcp_servers.rag-rat]\n default_tools_approval_mode = \"approve\"\n ```\n\n This trusts every current and future MCP tool exposed by the installed rag-rat plugin. Only enable\n it when you trust the plugin's source and installation origin, then restart Codex.\n\nThen open the repository and ask:\n\n> Set up rag-rat in this repo.\n\nThe `init-rag-rat` skill scans the repo, explains the material choices, previews `rag-rat.toml`,\nwrites and indexes only after confirmation, and offers to set up the git hooks that keep the index\nfresh. The MCP server starts dormant in an unconfigured repo; when setup finishes, reconnect it so it\nrestarts fully active against the new index.\n\nThen put it to work — the loop rag-rat is built for is in [Try it](#try-it).\n\n\nManual installation and other agents
\n\nUse this path for the standalone CLI, agents without plugin support, or building from source.\n\n### Install the CLI\n\nThe prebuilt package needs no Rust toolchain and supports Apple Silicon macOS, glibc ≥2.38 Linux\n(x86-64 and arm64), Windows x64, and Android/Termux arm64:\n\n```bash\nnpm install -g @rag-rat/bin\n# or run it without installing:\nnpx @rag-rat/bin --help\n```\n\n`@rag-rat/bin` fetches the full binary from the matching GitHub release. FastEmbed's ONNX Runtime is\nstatically linked.\n\nTo build from source instead:\n\n```bash\ncargo install rag-rat\n# or from a checkout:\ncargo install --path crates/rag-rat-cli --bin rag-rat\n```\n\nThe default source build needs glibc ≥2.38 and is unavailable for Intel macOS and musl/Alpine. On\nthose platforms, including Ubuntu 22.04, use the pure-Rust embedder:\n\n```bash\ncargo install rag-rat --no-default-features --features model2vec\n```\n\n`--no-default-features` alone produces a smaller hash-only build without real embeddings. SQLite is\nbundled; see [Platform support](#platform-support) for toolchain details.\n\n### Initialize the repository\n\n```bash\ncd /path/to/your/repo\nrag-rat init\n```\n\n`init` scans the repo, guides language and embedding choices, writes `rag-rat.toml`, and builds the\ninitial index. Use `rag-rat init --dry-run` to preview without writing, or `--yes` for\nnon-interactive defaults. Configuration reference: [`docs/config.md`](docs/config.md).\n\n### Add skills and connect MCP\n\nInstall the skills for Claude Code, Codex, Cursor, and 70+ other detected agents:\n\n```bash\nnpx @rag-rat/skills\n```\n\nThat installs `using-rag-rat`, `dream-review`, `init-rag-rat`, and\n`configure-rag-rat-dream`. See [`skills/README.md`](skills/README.md) for per-agent flags and\n`update`, `list`, and `remove`.\n\nThe MCP server uses STDIO: the client launches `rag-rat mcp` from the repository so it discovers the\ncorrect `rag-rat.toml` and repository scope in the consolidated machine-global store.\n\n```bash\nclaude mcp add --scope project rag-rat -- rag-rat mcp\ncodex mcp add rag-rat -- rag-rat mcp\n```\n\nOr add the equivalent project configuration:\n\n```json\n{\n \"mcpServers\": {\n \"rag-rat\": { \"command\": \"rag-rat\", \"args\": [\"mcp\"] }\n }\n}\n```\n\n`rag-rat init` prints the registration command but does not register the server itself. Pass\n`rag-rat mcp --json` if the client must parse JSON; tool text defaults to [TOON](#output). Full tool\nschemas: [`docs/mcp-tools.md`](docs/mcp-tools.md).\n\n\nClaude Code tool permissions
\n\nClaude Code asks once before each rag-rat MCP tool first runs. Choose \"Yes, don't ask again,\" or\nallow the tool namespace in `~/.claude/settings.json`:\n\n```json\n{ \"permissions\": { \"allow\": [\"mcp__rag-rat__*\"] } }\n```\n \n\n> **Do not pin a global server to one repository's config.** A user-scoped server with\n> `--config /some/repo/rag-rat.toml` serves that repository everywhere. Register MCP per project and\n> let the process discover the config from its working directory.\n\n \n\n## Try it\n\nOnce the repo is indexed, the code graph, symbols, git history, semantic search, and clone\ndetection are ready — these answer on the first query. Repo memories start **empty**: they accrue as\nagents record findings with `memory_create` and then surface automatically in later answers.\n(Tracker issue/PR rationale needs a `rag-rat papertrail sync`.)\n\nAsk your MCP client:\n\n- \"Run `impact_surface` on the function I'm about to edit — its callers, callees, tests, and recent\n commits.\"\n- \"Where is config reload handled?\" — hybrid `semantic_search` over source and docs.\n- \"What are the most load-bearing symbols in this repo?\" — `important_symbols`.\n- \"Does this helper duplicate anything already in the codebase?\" — `find_clones` (and the write-time\n hook warns as you write it).\n- \"Record an invariant on `parse_config`: reload must not allocate after the scheduler starts.\" —\n `memory_create` writes your first repo memory; it then rides along in future `impact_surface` /\n `symbol_lookup` results.\n\nOr from the CLI:\n\n```bash\nrag-rat query \"where is config reload handled?\"\nrag-rat important-symbols --limit 20\nrag-rat brief --mode spine\nrag-rat clusters --limit 10\n```\n\n## The agent loop\n\nThe point isn't the tool catalog — it's the loop an agent runs *around* an edit, so it changes code\nwith the callers, tests, rationale, and prior art in front of it instead of guessing:\n\n1. **Before editing a symbol, ask `impact_surface`.** One call returns the current source anchor,\n callers and callees, related tests, git/GitHub rationale, the repo memories bound to that\n symbol / path / call-path, and confidence + coverage warnings.\n2. **Read the blast radius, then edit.** The invariant a previous agent recorded, the caller three\n hops away, the test that pins the behavior — all surfaced before the change, not discovered after.\n3. **The clone hook catches duplication at write time.** If the new function reimplements code that\n already exists, the Write/Edit hook says so, with the existing symbol to reuse.\n4. **Record what you learned.** When the edit reveals a durable invariant, decision, or footgun,\n `memory_create` stores it as a source-anchored repo memory — so the next agent (or the next\n session) gets it in one call instead of re-deriving it.\n\nA trimmed `impact_surface` answer (TOON — the default output; abbreviated here) — every field is\nevidence, not prose:\n\n```text\nquery:\n ref: \"crates/config/src/config.rs::parse_config\"\n resolution: syntactic\ndirect_semantic_callers[12]:\n - from_symbol: \"crates/runtime/src/boot.rs::start\"\n edge_kind: calls_name\n confidence: syntactic\n callsite:\n path: \"crates/runtime/src/boot.rs\"\n line: 88\n importance:\n label: local structural load\n score: 6.8\n bucket: high\ntests_touching_symbol_path[4]:\n - path: \"crates/config/src/config_tests.rs\"\n reason: test_mentions_symbol_or_path\nrecent_commits_touching_symbol_path[1]:\n - evidence[1]: \"a1b2c3d touched crates/config/src/config.rs: fix reload race during startup (#141)\"\nrepo_memories:\n direct[2]:\n - kind: Invariant\n title: \"Config reload must not allocate after the scheduler starts\"\n confidence: high\n anchor_status: current\n binding_kind: symbol\n - kind: Decision\n title: \"TOML over JSON5 for the config surface (#88)\"\n anchor_status: current\n binding_kind: path\ncompleteness_and_caveats:\n exact_graph_callers: 12\n memory_status:\n active: 2\n stale: 0\n caveats[1]: \"Graph evidence is tree-sitter/syntactic, not compiler-grade name resolution.\"\n```\n\nAnd the write-time clone warning an agent sees before it duplicates logic — verbatim hook output:\n\n```text\n▶ rag-rat clone check — code you're writing duplicates existing functions:\n • `normalize_path_for_lookup` (line 42) is ~91% similar to crates/index/src/paths.rs::canonicalize_lookup_path\nPrefer reusing the existing function(s) over duplicating — impact_surface / symbol_lookup to inspect them.\n```\n\n## The tools\n\nrag-rat's **MCP tools** — the full catalog with JSON schemas lives in\n[`docs/mcp-tools.md`](docs/mcp-tools.md). The ones you'll reach for most:\n\n- **`impact_surface`** — the coding preflight from the loop above: callers, callees, tests, git\n history, GitHub papertrail, and the repo memories crossing a symbol, in one call. Memories default\n to compact, scannable headers; pass `full_memories: true` for full bodies + bindings.\n- **`semantic_search`** — hybrid BM25 + vector recall over source and docs, validated against current\n source. Every hit reports `retrieval_mode`; `explain=true` breaks down the score.\n- **`symbol_lookup`** — exact/fuzzy symbol resolution; cfg/overload variants grouped as one logical\n symbol.\n- **`find_callers` / `trace_callees`** — reverse/forward call-graph traversal (low-signal std/macro\n noise filtered by default).\n- **`important_symbols`** — the load-bearing symbols by (SCIP-aware) PageRank, seeded from your\n current diff by default; see [`docs/oracle.md`](docs/oracle.md).\n- **`find_clones`** — exact + near-miss duplicate functions ranked by refactor ROI (the candidate\n graph is precomputed in the background, so it scales to large repos).\n- **`memory_create`** — record a source-anchored repo memory; **`dream`** surfaces the maintenance\n worklist that keeps them honest ([below](#self-maintaining-memories)).\n\nBeyond these: repo orientation (`repo_brief`, `repo_clusters`), git/GitHub rationale\n(`commit_search`, `git_history_for_*`, `papertrail_for_*`, `rationale_search`), the full memory\ngraph (`memory_search`, `memory_edges`, `memory_rebind`, `memory_doctor`, …), graph-vs-compiler\naudit (`compare_graph_to_scip`), and index diagnostics (`index_status`, `llm_status`, `heal_index`)\n— all documented in [`docs/mcp-tools.md`](docs/mcp-tools.md).\n\n## Repo memories\n\nRepo memories are first-class local evidence — **not chat memory, not cloud personalization.** They\nare versioned, local, source-anchored facts about this repository. Each is typed\n(`Invariant`, `Decision`, `RejectedAlternative`, `Risk`, `BugPattern`, `PerformanceNote`, …) and\n**source-anchored**: bound to a logical symbol, concrete symbol, chunk, path+span, graph edge,\ncall-path, commit, or GitHub ref. rag-rat tracks each anchor as `current`, `relocated`, `stale`,\n`gone`, or `unverified`, and surfaces matching memories through the `memory_*` tools and inline in\n`read_chunk`, `symbol_lookup`, `find_callers`, `trace_callees`, and `impact_surface`. They're how\nhard-won context reaches the *next* agent in one call instead of evaporating.\n\nMemories are also a **typed graph**, not just a flat list: `memory_edge_add` / `memory_edges` connect\nthem with relations (`depends_on`, `relates_to`, `supersedes`, `derived_from`, `tracks`) — a task DAG,\na mind-map link between decisions, or a task that `tracks` a GitHub issue. Full tool list:\n[`docs/mcp-tools.md`](docs/mcp-tools.md#repo-memories).\n\n## Self-maintaining memories\n\nMemories rot: the code moves under them, an invariant gets superseded, a load-bearing function ships\nwith no memory at all. **`dream`** is the maintenance loop that keeps the layer honest. It recomputes\na ranked worklist of findings *about* the memories themselves — each with a stable id to review:\n\n- **coverage gaps** — load-bearing symbols (by the same PageRank as `important_symbols`) that carry no\n memory, so the next agent editing them gets nothing.\n- **stale references** — a memory citing a path or anchor that no longer resolves.\n\n`dream` runs the deterministic findings on every call. Two opt-in **model passes** go deeper, running\na small model on an ephemeral remote GPU (`[llm.dream.remote]`) only when work is pending:\n`rag-rat dream --verify` recomputes each memory's verdict against current source *reality* (has the\ncode drifted from what the memory claims?), and `--compact` rewrites a verbose memory to a tighter\nsummary. Findings those passes persist surface back through `dream`.\n\nNothing is deleted automatically. A human — or a strong agent over MCP — burns the worklist down with\n**`dream_review`** (`accept` a real gap, `dismiss` noise, `reset` a prior verdict), and verdicts\nsurvive future runs so settled findings don't come back. It's the same surface as the CLI\n`rag-rat dream` / `rag-rat dream --accept|--dismiss|--reset`.\n\n## Compiler-grade resolution & ranking\n\nThe graph is heuristic by default. The opt-in **SCIP oracle** (`rag-rat oracle run`) upgrades edges\nto a `Compiler` tier from a real language tool, recovers calls tree-sitter missed, flags external\nedges, and makes `important_symbols` surface the genuine god-modules. For C/C++ the `scip-clang`\noracle distinguishes declarations from definitions and sharpens call/type edges in macro-heavy or\nmulti-target code — the difference between usable and noisy graphs on firmware, kernels, drivers, and\nSDKs. Turn on `[oracle] auto_run` and the MCP server keeps it fresh on its own (throttled,\nwatcher-safe). Full details: [`docs/oracle.md`](docs/oracle.md).\n\n## Freshness\n\n`rag-rat mcp` runs a background file watcher (on by default; `[watch] enabled = false` or\n`RAG_RAT_NO_WATCH=1` to disable), so graph/symbol queries reflect uncommitted edits without a commit.\nIndexed rows are git-context-aware: clean files are stored by `commit_sha`, dirty/untracked files in\na worktree overlay, so one database reuses rows across branch switches while reflecting local edits.\nOptional git hooks (`rag-rat hooks install`) keep the index current on checkout/merge/rewrite/commit.\n`read_chunk` and search validate hits against current source and heal stale entries before returning.\n\nOne watcher per worktree and one writer at a time are enforced with file locks (unreliable on\nNFS / WSL2 `/mnt` mounts).\n\n## Editor Lens HTTP API\n\nAn active `rag-rat mcp` process also elects one authenticated Lens HTTP server per worktree. It\npublishes the loopback URL and bearer token to `.rag-rat/sockets/lens.json`; the credential file is\nowner-readable only on Unix. Set `RAG_RAT_NO_LENS=1` to disable this embedded server, or set\n`RAG_RAT_LENS_ORIGINS` to a comma-separated exact browser-origin allowlist.\n\nRun `rag-rat serve` when the HTTP API needs its own lifecycle. Loopback serving generates a token;\nclients read it from the discovery file. A non-loopback bind requires both an explicit token\nenvironment variable and at least one trusted browser origin:\n\n```bash\nLENS_TOKEN=\"$(openssl rand -hex 32)\" rag-rat serve \\\n --bind 0.0.0.0 --token-env LENS_TOKEN --allow-origin https://lens.example.com\n```\n\nEvery non-preflight request uses `Authorization: Bearer `. Allowed origins are matched\nexactly; wildcard CORS is never emitted. The built-in listener is plain HTTP, so terminate TLS in a\ntrusted reverse proxy or tunnel before exposing a non-loopback server across an untrusted network.\n\nBy default every repo's index and memories live in **one consolidated database per machine**\n(`$XDG_DATA_HOME/rag-rat/rag-rat.sqlite`; override with `RAG_RAT_DATA_DIR`), so a deleted checkout or\n`git clean -fdx` no longer loses your authored memories. Set an explicit `[index] database` to keep a\nrepo on its own file (deprecated), and run `rag-rat consolidate` to import a pre-existing\n`.rag-rat/index.sqlite` into the global store — see [docs/config/database.md](docs/config/database.md).\n\n## Output format\n\nThe CLI and MCP results default to **TOON** (Token-Oriented Object Notation) — a token-efficient\nencoding that renders uniform rows as a dense `[N]{cols}:` table (~30% smaller than compact JSON on\nthose payloads, never larger in practice). Pass `--json` (CLI, either position) or launch\n`rag-rat mcp --json` (MCP) when a JSON parser must read the output.\n\n## Embedding backends\n\nThe default local embedder (FastEmbed) needs no setup, but a large repo or a stronger model is worth\noffloading. rag-rat speaks the **OpenAI-compatible `/v1/embeddings` API**, so a `[llm.embedding.remote]`\nblock can serve embeddings from **Ollama, vLLM, or michaelfeil/infinity** — one client, one place to\naudit and secure. Two modes:\n\n- **Connect** to a server you already run (set `endpoint`).\n- **Ephemeral** — let the bundled cookbook provision a GPU worker (**Modal / RunPod**) just for the\n backfill and tear it down afterward (set `cookbook`); pick the backend and GPU class in config.\n\nThe init flow warns when a **short-context model would truncate long code chunks** and steers you to a\nlong-context code embedder, and rag-rat **auto-tunes the client concurrency** against the chosen\nbackend so the sweep finds its throughput knee. Setup and every knob: [`docs/config.md`](docs/config.md).\n\n## Retrieval quality\n\nSearch quality is measurable, not guesswork. rag-rat ships a **commit-replay evaluation harness**\n(`rag-rat eval --replay`): each recent commit becomes a case — its message is the query, the files it\ntouched are the gold set — and search is scored on how well it recovers them. It reports **recall@3**\n(did the right chunk land in the first three reads?), recall@10, and MRR@10, and CI tracks the trend\non [Bencher](https://bencher.dev/perf/rag-rat/plots) on `main` so a regression is caught before it\nships.\n\nReach for it when comparing embedding models, changing chunking, enabling int8 vector storage\n(smaller on disk), or tuning a remote backend — you can prove the change didn't cost recall instead\nof hoping. (`rag-rat eval` requires a `--features eval` build; it is absent from the released binary.)\n\n## Benchmarks\n\nThe headline workload is indexing the whole Linux kernel (v7.0, ~63k C/H files, 9.14M graph edges).\nFull numbers — wall-clock, throughput, peak RSS, on-disk size, unresolved-edge taxonomy — are in\n[`docs/benchmarks.md`](docs/benchmarks.md). Performance is tracked per-push and gated per-PR; the live\nhistory is at [bencher.dev/perf/rag-rat/plots](https://bencher.dev/perf/rag-rat/plots) (wiring:\n[`docs/bencher.md`](docs/bencher.md)).\n\n## Security\n\nThe MCP server exposes read-only source tools. It never executes shell commands or writes your source\nfiles. It writes only the configured SQLite index — during indexing, migration, maintenance,\nreconciliation, repo-memory operations, and automatic stale-index healing. GitHub sync is explicit\nand uses `gh api`; normal query tools read only the local cache.\n\n### Local vs remote embedding\n\nWith the **default local embedder, nothing leaves the machine** — indexing and querying are entirely\nlocal. Configuring a `[llm.embedding.remote]` backend is what sends text off the box, in two places:\nthe **chunk text** selected at index time, and the **query text** of each semantic search (a search\nembeds your query to compare it against the indexed vectors). A CONNECT backend embeds both against\nthe configured `endpoint`; an ephemeral backend embeds queries against the local `query_endpoint`.\n\nWhat the endpoint *is* decides how much that matters:\n\n- **Your own server** (self-hosted Ollama / vLLM / infinity) — the text stays in infrastructure you\n control.\n- **Ephemeral Modal / RunPod workers** (the cookbook path) are ephemeral *compute* providers running\n *your* open-source embedder, not data services that train on inputs. Both are SOC 2 Type II, encrypt\n in transit and at rest, isolate tenants, and tear the box and its storage down after the backfill —\n a data-processor relationship, reasonable for proprietary code the same way a cloud VM is.\n- **A third-party embedding API** you don't control is the one to actually read the terms on\n (retention, training on inputs).\n\nSensible hygiene regardless of backend: exclude secrets, generated files, and vendor trees from the\nindexed targets so they're never chunked or embedded, and keep secrets out of query text. Details:\n[`docs/config.md`](docs/config.md).\n\n## Platform support\n\nrag-rat builds and tests on Linux, macOS, and Windows. Linux is covered on every PR and on every\npush to main; macOS and Windows are exercised on release, so `cargo install rag-rat` builds and\nlinks on all three. Android (aarch64, bionic) is also a release target — a prebuilt binary is\nattached to each release and published to `@rag-rat/bin`, so `npx @rag-rat/bin` works on Termux; see\n[Quickstart](#quickstart).\nSQLite is bundled (compiled from source via `rusqlite`), so there's no system-library prerequisite,\nbut each platform needs a C toolchain: Linux ships one; on macOS install the Xcode Command Line\nTools (`xcode-select --install`); on Windows install the Visual Studio Build Tools with the C++\nworkload (MSVC). Requires **Rust 1.96+**; the workspace tracks that stable baseline for its\ndependencies (the bundled SQLite build itself requires at least Rust 1.95 for `cfg_select!`).\n\nA few maintenance conveniences are Unix- or Linux-only by design and degrade quietly elsewhere — no\nfeature of the index, query, or MCP surface is affected:\n\n- **Hot-upgrade of a running MCP server** (the `SIGUSR1` in-place re-exec) is Unix-only. On Windows,\n restart `rag-rat mcp` to pick up a new binary.\n- **Fleet auto-upgrade** (signalling other running servers when a new binary lands) is Linux-only —\n it walks `/proc` — and is a no-op elsewhere.\n- **The grep-augmentation hook** uses a warm Unix-socket listener (with per-session dedupe) on\n Linux and macOS; on Windows it falls back to a per-call read-only query straight against the\n index, which works the same but without cross-call dedupe.\n\n## Commands\n\n```bash\nrag-rat init # guided first-run setup\nrag-rat index [--changed|--discover|--full]\nrag-rat doctor\nrag-rat query \"semantic recall\" # add --json for JSON\nrag-rat important-symbols --limit 20\nrag-rat brief --mode spine|churn|god_modules|refactor_candidates\nrag-rat clusters --limit 10\nrag-rat oracle run | status # compiler-grade resolution (docs/oracle.md)\nrag-rat models list | install \nrag-rat reconcile --changed-first --max-seconds 60 --batch-size 64\nrag-rat papertrail sync # add --full to force a historical healing pass\nrag-rat memory list | show | doctor | rebind # inspect / re-anchor repo memories\nrag-rat dream [--verify|--compact] [ --accept|--dismiss|--reset] # memory-maintenance worklist\nrag-rat consolidate # import a legacy per-repo index into the global store\nrag-rat hooks install # git maintenance hooks\nrag-rat gc # prune rows for dead git contexts\nrag-rat eval [--json|--update-baseline] # CI search-quality gate; requires a `--features eval` build (absent from the released binary)\nrag-rat serve # authenticated editor Lens HTTP API\nrag-rat mcp # start the STDIO server\n```\n\n## Releasing & license\n\nReleases are automated by [release-plz](https://release-plz.dev) (the three crates ship in lockstep;\nsee [`docs/releasing.md`](docs/releasing.md)). `rag-rat` is MIT-licensed — see [LICENSE](LICENSE).\n\n## Prior art\n\nrag-rat's clone-detection design is inspired by SourcererCC's scalable token-bag candidate\ngeneration, NiCad's normalized near-miss clone-detection framing, GumTree's move-aware AST\ndifferencing, and anti-unification / least-general generalization for template extraction. Planned\nfragment-level mining and copy-paste bug heuristics are inspired by CP-Miner.\n",
"bytes": 28564,
"sha": "d110a443fe42cfcc7474d52da5ebeb471eb94ef7ea0653c219c35f1884b77fa9",
"repo_slug": "cq27-dev/rag-rat",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cq27_dev_rag_rat_696880ec/readme"
}