Code RAG (retrieval-augmented generation over source code) indexes a codebase into searchable units, retrieves the most relevant snippets for a query or task, and puts them into the LLM's context before it answers or edits. It is how AI coding assistants answer questions about repos that are far larger than the model's context window.

Why does chunking matter for code RAG?

A chunk that cuts a function in half embeds as neither half's meaning. AST-aware chunking keeps each chunk a complete semantic unit — a function, a class, a method — so embeddings describe real code, and class-level header chunks give the indexer a handle for methods defined far from their class. It is the single biggest accuracy lever in code RAG.

How do I run RAG on my own codebase locally?

With Open Context Engine: npm install -g @dhaxor/open-context, then oce index (builds a local SQLite index with AST-aware chunks, hybrid retrieval, and a code graph), then oce search "your question" to query it, or claude mcp add oce -- oce mcp to serve it to Claude Code over MCP. Embeddings run in-process by default, so nothing leaves your machine.

How do you measure code RAG quality?

With committed gold sets — query/expected-chunk pairs scored with recall@k, MRR, and nDCG in CI, the way tests are. Open Context Engine publishes its numbers on its benchmarks page: hybrid recall@10 of 0.943 on its own repo and parity (0.926) on Flask 3.1.2 where pure vector search previously lost. If a tool doesn't publish retrieval metrics, its accuracy claims are vibes.

guides/code-rag 1.00

Code RAG: retrieval-augmented generation for your codebase

Q: How is code RAG different from general RAG?

Code has structure that prose does not: functions, classes, imports, and call graphs. Good code RAG chunks along AST boundaries (not fixed line counts), fuses dense embeddings with exact keyword matching (identifiers like AbortWithStatusJSON are lexical queries, not semantic ones), expands results along the code graph (callers and callees), and resolves symbol definitions. General-purpose RAG pipelines skip all of this and it shows in accuracy.

How RAG over source code works, why the naive recipe fails on real repositories, and how to run it locally — with retrieval quality you can measure.

What is code RAG?

Code RAG is retrieval-augmented generation applied to source code: index a codebase into searchable units, retrieve the ones relevant to the current task, and put them into the model's context before it answers or edits. It exists because a real repository is orders of magnitude larger than any model's context window — so an AI assistant's grounding is only as good as its retrieval.

Every AI coding tool you use is doing code RAG under some other name. When Claude Code answers "where do we validate JWTs?", when Cursor suggests a fix in the file you haven't opened, when a PR-review bot flags a broken caller — a retriever chose what code the model saw. Weak retrievers produce the classic failures: hallucinated APIs, edits to the wrong file, "fixes" that break code the model never saw.

Why naive code RAG fails

The default recipe — split files every N lines, embed the chunks, cosine-search them — falls over on real codebases in three distinct ways:

Line-count chunking severs meaning. A chunk that cuts a function in half embeds as neither half's meaning. Retrieval then ranks garbage confidently.
Plain vector search misses exact identifiers. "Find AbortWithStatusJSON" is a lexical query — the answer is the chunk containing that exact token, not its nearest neighbors in embedding space. Semantic similarity alone won't rank it first.
Plain keyword search misses paraphrases. "How does auth middleware work" never names authMiddleware. Lexical matching alone won't find it.

Each failure mode rules out half the query space. That's why production code RAG needs both retrieval signals — and the structure code uniquely provides.

What good code RAG looks like

The pieces that separate measured retrieval from a demo:

AST-aware chunking. Chunk along tree-sitter parse boundaries — functions, classes, methods — across languages, so every chunk is a complete semantic unit. Add class-level header chunks so methods defined far from their class still surface for class questions.
Hybrid retrieval. Dense embeddings fused with BM25 keyword scoring via Reciprocal Rank Fusion — semantics for paraphrases, exact match for identifiers, one ranking that benefits from both.
Symbol expansion. When a retrieved snippet calls validateToken(), pull in validateToken's definition alongside — the model sees the callee without a second round-trip.
A code graph. Import/call/definition edges extracted from the AST, so results ride with their callers and callees.
Compiler-grade symbol lookup. A language server turns "where is this defined / who references it" from fuzzy guessing into exact answers.
Measurement. Committed gold sets scored with recall@k, MRR, and nDCG in CI — published numbers, not vibes.

Run code RAG locally in three commands

Open Context Engine is a code-RAG engine you can run over your own repository — local, private, and free (MIT core):

npm install -g @dhaxor/open-context
oce index                        # AST-aware chunks + hybrid index + code graph, in local SQLite
oce search "where do we validate JWTs?"

Embeddings run in-process (MiniLM by default — no API key), everything lives in local SQLite, and if the vector extension is unavailable the engine degrades to keyword-only BM25 instead of dying. To give an agentic workflow this grounding, serve it over MCP — the MCP server guide covers Claude Code and Cursor in one command each.

Measure before you trust

The uncomfortable question for any code-RAG tool: what's your recall@10? If a vendor can't answer with a methodology — gold sets, scoring metrics, before/after for ranking changes — its accuracy claims are marketing. OCE treats retrieval quality like tests: committed gold sets (this repo, Flask 3.1.2, gin v1.10.0), CI baselines, and a public benchmarks page generated from the eval harness's own reports. The harness ships with the product, so you can score it on your own codebase too.

Why not just fine-tune on the codebase?

A common alternative — training a model on your source — answers a different question. Fine-tuning shapes how a model writes; retrieval supplies what it knows, freshly, with citations. Code changes every commit, so frozen weights go stale where a re-indexed answer doesn't. The full comparison is in RAG vs fine-tuning for code.

Frequently asked questions

What is code RAG?

Retrieval-augmented generation over source code: index a repo into searchable units, retrieve what's relevant to the task, and put it in the model's context before it answers or edits. It's how AI assistants handle codebases bigger than the context window.

How is code RAG different from general RAG?

Code has machine-checkable structure: ASTs, imports, call graphs, symbol tables. Good code RAG chunks on AST boundaries, fuses semantic + keyword retrieval, expands along the code graph, and resolves symbol definitions — none of which general text RAG needs.

Why does chunking matter so much?

Because a chunk that halves a function embeds as neither half's meaning. AST-aware chunking keeps chunks semantically complete, which is the biggest single accuracy lever in the pipeline.

Can code RAG run fully offline?

Yes. With OCE, embeddings run in-process with no API key and the index is local SQLite; keyword-only mode covers environments where vector search is unavailable. Nothing is uploaded.

How do I evaluate a code RAG system?

Build or use committed gold sets and score recall@k, MRR, and nDCG — OCE's benchmarks page shows the method and the numbers, and oce eval reproduces the harness on your own repo.