Skip to main content
Glama
README.md
# Local Code RAG

Local semantic code search for Claude Code: index folders (Unreal projects, engine source, anything), embed them on-device with FastEmbed/ONNX, store them in LanceDB, and expose hybrid (vector + BM25) search over MCP. A Tauri v2 desktop app manages the indexes.

```
crates/rag-core   indexing, chunking, embeddings, LanceDB storage, config, file locks
crates/rag-mcp    headless MCP server (stdio, rmcp)
src-tauri + ui/   Tauri v2 desktop manager (React + TS + Tailwind v4)
```

## Build

Requirements: Rust ≥ 1.94, Node 22, `protoc` (LanceDB dependency).
Windows: MSVC build tools + WebView2 (preinstalled on Win10/11).

```powershell
# MCP server (CUDA by default; falls back to CPU at runtime if CUDA/cuDNN are missing)
cargo build --release -p rag-mcp
cargo build --release -p rag-mcp --no-default-features                       # CPU only
cargo build --release -p rag-mcp --no-default-features --features directml   # AMD/Intel DX12 GPUs

# Desktop app: bundles rag-mcp + the ONNX Runtime CUDA provider DLLs next to the exe
npm ci
npx tauri dev                       # development (run `cargo build -p rag-mcp` once first)
npx tauri build                     # installer in target/release/bundle
$env:RAG_FEATURES="none"; npx tauri build      # CPU-only bundle
```

**CUDA:** the user's machine needs the **CUDA 13** runtime + **cuDNN 9 (for CUDA 13)** on `PATH` (not bundled, ~1 GB) and a recent NVIDIA driver. The pinned ONNX Runtime (`ort 2.0.0-rc.15`) only ships CUDA 13 prebuilt binaries; with CUDA 12 installed it silently runs on CPU. The GUI's chunks/sec readout shows whether the GPU is actually used (CPU is ~10–30x slower).

ONNX Runtime binaries are downloaded at build time by `ort`; models are downloaded from Hugging Face on first use into `<data dir>/models`.

## Data layout

`%APPDATA%\local-code-rag\` (Windows) · `~/.local/share/local-code-rag/` (Linux) · override with `LOCAL_CODE_RAG_HOME`.

```
config.json              global settings + per-index config (schema below)
manifests/<id>.json      relative_path -> {blake3, size, mtime}
locks/<id>.lock          fs2 advisory lock (GUI indexing vs MCP search/auto-sync)
lancedb/idx_<id>.lance   chunks: path, start_line, end_line, text, vector
models/                  FastEmbed ONNX cache
```

`config.json` follows the blueprint schema (`active_embed_model`, `execution_provider` = `auto|cuda|directml|cpu`, `indexes[]` with `root_path`, `embed_model`, `allowed_extensions`, `ignore_dirs`, `chunk_size`, `chunk_overlap`, `auto_update_on_search`, `auto_update_cooldown_hours`, `last_indexed_at`, `chunk_count`), plus global `embed_batch_size`, `reranker_model`, `rerank_candidates`, `auto_sync_max_files`, `snippet_max_lines` and `description` / `max_file_bytes` (per index).

## How indexing works

1. Walk `root_path` with `ignore` (respects `.gitignore`; skips `ignore_dirs` by name at any depth, case-insensitive; filters by extension; skips files > `max_file_bytes`).
2. Hash with blake3 — files whose size + mtime match the manifest are not re-read, so a no-change sync of a large tree is just a directory walk.
3. Diff against the manifest → delete chunks of removed/modified files.
4. Chunk new/modified files: tree-sitter AST splitting for C/C++/HLSL (`.usf/.ush`), Rust, C#, Python; plain-text splitter otherwise. Each chunk keeps its 1-based line range.
5. Sort chunks by length (minimises ONNX padding), embed in batches (`embed_batch_size`, default 32), flush to LanceDB every 2048 rows. The embedded text is prefixed with the file path for context.
6. Rebuild the full-text index on `text` (no stemming / stop words — code-friendly), a scalar index on `path`, and an ANN vector index once a table exceeds 100k rows; then compact.

Changing an index's model or chunk settings changes its fingerprint → next sync is a full rebuild (the GUI warns and offers to do it now). Cancelling keeps all completed files; the next sync resumes.

Search embeds the query (with the model's query prefix for BGE/Nomic), runs LanceDB hybrid search (vector + BM25, fused with Reciprocal Rank Fusion) over the top `rerank_candidates` (30), re-scores them with a cross-encoder (`reranker_model`, default `jinaai/jina-reranker-v2-base-multilingual`, `null` disables), and returns the top `limit`. Each result is trimmed to the `snippet_max_lines` (40) lines that best match the query terms (identifiers are split on `::` and camelCase), labelled with the original chunk range.

**Auto-sync on search** only runs inline when at most `auto_sync_max_files` (200) files changed and no full build is needed. Otherwise the search answers from the existing data with a note asking for "Index now" in the app (or `reindex_path`), so a tool call never blocks on a multi-minute build.

> Note: current LanceDB versions ship their own native BM25 inverted index instead of the older Tantivy-based one; the behaviour is the same (hybrid + RRF), with no extra dependency.

## MCP tools

| Tool | Purpose |
|---|---|
| `list_indexes()` | ids, names, roots, models, chunk counts, last update, status |
| `search_index(index_id, query, limit=6)` | hybrid search; incremental auto-sync first if `auto_update_on_search` and past cooldown |
| `reindex_path(index_id, force_full=false)` | manual sync |

Logging goes to stderr only (`RUST_LOG` to adjust). If the GUI is indexing, auto-sync is skipped and search proceeds against the last committed data (LanceDB reads are MVCC-safe).

Register (or use the **Install to Claude Code** button, which also generates a CLAUDE.md snippet):

```powershell
claude mcp add --transport stdio --scope user local-code-rag -- "C:\Program Files\Local Code RAG\rag-mcp.exe"
claude mcp list
```

### Per-project AGENTS.md

Each index card has an **AGENTS.md** button that generates a paste-ready paragraph for that project's `AGENTS.md` / `CLAUDE.md`: its index id, root path and file types, when to call `search_index` vs. `reindex_path`, and the other indexes (e.g. engine source) the agent can also search. Generated by `rag_core::agents_md::agents_md_snippet`.

## Tests

```
cargo test -p rag-core                        # unit tests (walker, manifest diff, chunker, model resolution)
cargo test -p rag-core -- --ignored           # end-to-end: downloads bge-small, indexes, searches, syncs
```