Local-first · Open source · MIT

Ask any repository how it actually works — and trust the answer.

RepoLens reads a codebase the way a careful contributor does: it parses the real source, retrieves the relevant functions, and answers only from what's on disk — every sentence carrying a file:line citation you can open and check. No training-data guesses. No confident hallucinations.

Get started Read the source
$ pip install repolens-rag
  • PyPI version
  • Python 3.11+
  • License MIT
0uncited sentences allowed
8languages parsed with tree-sitter
4LLM backends, incl. fully local
100%of your data stays on disk

०१ The problem

New contributors hit a cold-start wall — and so do the tools meant to help.

Docs drift from code

READMEs and docstrings rot the moment behaviour changes. The "default timeout is 30s" line survives long after someone changed it to 10. You can't tell which lines still hold.

Assistants hallucinate confidently

A general LLM "remembers" an older version of the project from its training data and answers in a tone of total certainty — about code that no longer exists at this commit.

No verifiable ground truth

There's no tool that answers "how does X actually work, in this repo, at this commit" and hands you the evidence to check it yourself.

०२ Three pillars

Built so the answer is the evidence — not a guess about it.

✦

Grounding enforcement

Every answer sentence must cite a file:line span. A citation validator re-opens the file and verifies the range exists and is relevant; a bad citation forces a regeneration (up to two retries) rather than slipping through. If retrieval finds nothing, RepoLens says "not found in this codebase" instead of inventing one.

⧉

Code-native retrieval

Source is parsed with tree-sitter into semantic units — functions, classes, structs — each carrying its signature and docstring. A symbol graph tracks caller/callee links so neighbours come along for context. Search is hybrid: dense embeddings + BM25, fused with RRF, then re-ranked by a cross-encoder.

⟲

Doc-drift detection

A separate mode indexes documentation and code apart, extracts factual claims from the docs, and runs NLI entailment against the matching code: supported, contradicted, or not found. Out comes a Markdown report of stale docs — doc location beside code location — that fails CI on new findings.

०३ Under the hood

A real retrieval pipeline, not a wrapper around a prompt.

tree-sitter parsing

Semantic chunking into functions/classes/structs with signatures & docstrings, across Python, Go, JS, TS, Rust, C, C++, and Java.

Hybrid search + RRF

Dense jina-embeddings-v2-base-code vectors and BM25 keyword matches, fused with Reciprocal Rank Fusion.

Cross-encoder rerank

A ms-marco-MiniLM reranker re-scores the fused candidates so the most relevant code rises to the top.

Symbol graph expansion

A NetworkX caller/callee graph pulls in the functions around a match so answers see the call context, not an island.

NLI grounding score

Every answer gets an entailment score (0–1) from nli-deberta and a high/medium/low verdict shown in the UI.

Citation validation

Cited ranges are re-opened on disk and verified before the answer is allowed out — invalid citations trigger a regenerate.

Doc-drift report

Claim extraction + NLI produce a CI-friendly Markdown report; --ci exits non-zero on new stale-doc findings.

Local-first storage

LanceDB vectors, BM25 index, symbol graph and SQLite metadata all live under ~/.repolens. Nothing leaves your machine but the LLM call.

Four LLM backends

Groq (free, default), OpenAI, Anthropic — or Ollama for fully offline inference with no rate limits.

Streaming web UI + CLI

A FastAPI server streams tokens, citations and grounding over SSE to a React "Observatory" UI; a typer CLI does the same headless.

.repolensignore

Gitignore-style excludes (vendored code, virtualenvs, generated files) are applied before a single file is parsed.

Pip-installable

One pip install repolens-rag ships the CLI, the API, and the prebuilt web UI as a single process on one port.

०४ How it works

From a folder on disk to a cited answer.

  1. 01

    Index

    Walk the repo (honouring .repolensignore) → parse with tree-sitter → chunk semantically → build the symbol graph → embed + BM25 → persist to ~/.repolens.

  2. 02

    Retrieve

    Hybrid dense + BM25 search → RRF fusion → cross-encoder rerank → graph expansion to pull in callers and callees of the top matches.

  3. 03

    Generate & verify

    A grounded prompt asks the LLM to answer only from the retrieved chunks with citations → the validator re-checks every file:line → the NLI scorer rates the grounding.

  4. 04

    Detect drift

    Separately: extract claims from docs → retrieve matching code → NLI verdict (supported / contradicted / not found) → a Markdown report that can gate CI.

०५ Quickstart

Three commands to a grounded answer.

  1. Install

    $ pip install repolens-rag

  2. Add a free LLM key

    $ export GROQ_API_KEY=gsk_…

    Grab a free key at console.groq.com — or skip the cloud entirely with the Ollama backend.

  3. Index & serve

    $ repolens serve

    Opens the Observatory UI at localhost:8000 — add a repo, ask away.

०६ Tech stack

Boring, dependable parts — wired together carefully.

  • Python 3.11+
  • FastAPI
  • typer + rich
  • tree-sitter
  • jina-embeddings-v2-base-code
  • LanceDB
  • rank-bm25
  • NetworkX
  • cross-encoder rerank
  • nli-deberta
  • SQLite
  • React 18 + Vite
  • Tailwind CSS
  • SSE streaming
  • Groq · OpenAI · Anthropic · Ollama

०७ Who it's for

Anyone who needs the truth about a codebase, fast.

New contributors

Onboard onto a large OSS project without spelunking for days — ask, get cited code, follow the trail.

Maintainers

Catch stale docs automatically in CI, and answer "where is this handled?" without re-reading the module.

Reviewers & auditors

Trace behaviour to exact lines at a specific commit — answers you can verify, not vibes.

Teams with private code

Local-first by design: indexes and embeddings stay on disk; only the LLM call leaves (and Ollama keeps even that local).

०८ Questions

Frequently asked.

Does it work offline?

The embedder, reranker and grounding models all run locally. With the Ollama backend, generation is local too — RepoLens then makes zero network calls.

What stops it from hallucinating?

Three guards: answers must cite file:line spans; a validator re-opens each cited range; and if retrieval returns nothing relevant, it returns a structured "not found" instead of letting the model fill from memory.

Which languages are supported?

Python, Go, JavaScript, TypeScript, Rust, C, C++ and Java — parsed via tree-sitter grammars. More can be added by wiring up the grammar.

How does drift detection fit into CI?

Run repolens drift --ci; it exits non-zero when new stale-doc findings appear, so a pull request that lets docs drift from code fails the check.

Is my code uploaded anywhere?

No. Vectors, the BM25 index, the symbol graph and metadata all live under ~/.repolens. The only outbound traffic is the LLM API call — and only for the cloud backends.

Does it run on Windows?

Yes — the package is pure-Python and its native dependencies ship Windows wheels. Use Python 3.11 or 3.12 and have Git installed.

Stop guessing what the code does.

Index a repository in minutes and get answers you can actually open and verify.

Install from PyPI View on GitHub