A local semantic code search and generation CLI
ragcodepilot indexes source repositories locally with Go AST function-level chunking, embeds code via Ollama (nomic-embed-text), indexes BM25 keywords, and executes server-side Reciprocal Rank Fusion (RRF) inside Qdrant — optionally generating answers with source citations via --answer.
Implementation reviewed — · revision — ↗. Evaluation dates appear with their reports.
go run ./cmd/ragcodepilot search --answer "how does chunking work?"
Content reviewed —. The implementation revision and experiment revisions are separate: a website refresh is not a new benchmark or release certification.
Local CLI with hybrid retrieval, opt-in answers, and index --watch.
.gitignore, and actionable errors.Saved self/chi recheck: —, source —.
In-place updates are not atomic snapshots. Sparse refresh and upserts remain scope-wide. These are acceptance boundaries, not claims that the mechanisms are absent.
Start with where the work runs, then select a stage to inspect its input, output, and a simplified code example.
Reads source files, chunks and enriches code, builds BM25 vectors, and orchestrates search. Prints ranked code by default.
HTTP → Ollama · gRPC → Qdrant
/api/embed creates dense vectors. With --answer, /api/chat generates text from retrieved chunks.
Sparse-only search skips embeddings.
Persists vectors and raw source payloads. Applies filters and performs dense/sparse retrieval and hybrid RRF fusion.
Lookup and fusion share one query RPC.
code_chunksShared Qdrant collection: dense + sparse + raw code payload
Search reads
The diagrams show logical data flow, not concurrent Go workers. Search returns code directly; the separate --answer branch sends context to the LLM. Selecting a diagram does not change the simulator below.
Applies language, hidden-file, and config.yaml exclusions, then Git's nested .gitignore rules. Negation cannot restore paths already excluded by configuration or hidden-file rules. Default exclusions include .git, vendor directories, and *_test.go.
Simplified example · View implementation ↗
Five scripted examples show which stages run in each mode. Rankings, vectors, and answers are illustrative; this page does not call Qdrant or Ollama. Unsupported queries return no demo.
Simulated only. Modes rank a fixed illustrative candidate set. Reference numbers identify example sources, not result ranks. No timings are measured here.
No scripted demo for that query. Pick a preset below. This is a demo limitation, not evidence that the real index has no match.
Code excerpts are simplified for explanation. Use each source link to inspect the implementation at the documented revision.
The same ChunkFile function moves from a local file to a cited answer. Source text is real; the abbreviated payload and answer below are teaching examples.
The walker selects internal/ingest/chunker.go. The Go parser retains the function and its doc comment, lines 20–28, as one named chunk.
// ChunkFile reads a source file and splits it into chunks.
// For Go files, it uses go/parser to produce function-level chunks.
// For all other languages, it falls back to a line-based sliding window.
func ChunkFile(filePath, repoRoot, repo string, chunkSize, overlap int, cfg *config.Config) ([]model.CodeChunk, error) {
if cfg.DetectLanguage(filePath) == "go" {
return chunkGoFile(filePath, repoRoot, repo, chunkSize, overlap, cfg)
}
return chunkGeneric(filePath, repoRoot, repo, chunkSize, overlap, cfg)
}Prefix the code with this header. The enriched text is used for dense embeddings and sparse document vectors; the original code remains the stored payload.
File: internal/ingest/chunker.go
Language: go
Function: ChunkFile
[the same source text from step 1]The CLI reuses a validated dense vector or calls Ollama on a cache miss, builds BM25 document weights using scope-wide statistics, then upserts both over gRPC.
collection: code_chunks
vectors: dense [768 floats], sparse {term IDs, BM25 weights}
payload: {repo, file_path, language: go, name: ChunkFile,
chunk_type: function, start_line: 20, end_line: 28,
content: original source, file_hash, index_version}Query: “where is ChunkFile defined”. Hybrid mode embeds it and tokenizes it into sparse terms with weight 1.0 each. Qdrant filters both candidate lists and fuses their positions with RRF.
The saved September 23 post-merge self run returned this function at rank #1. Its source revision is separate from the implementation review; this is not a guarantee for other corpora.
Default: return ranked code chunks. With --answer: warm the local generator, select up to --answer-limit chunks (default 5), build the prompt, and call Ollama /api/chat.
“ChunkFile is defined in internal/ingest/chunker.go. It dispatches Go files to the AST chunker and other files to the generic chunker. [1]”
[1] Inspect the original function ↗
Illustrative answer. Citations make evidence inspectable; their presence alone does not prove the explanation is correct.
Success: index → retrieve → code results → optional cited answer.
Explore the foundational algorithms and engineering decisions that power high-precision code retrieval.
Parses Go with go/parser. Keeps function/method declarations and named types/interfaces together when they fit. Declarations longer than 80 lines use sliding-window splitting; syntax errors fall back to the generic chunker.
Used for languages without dedicated AST parsers (Python, TypeScript, Shell). Slices files into 40-line windows with a 5-line overlap, using regex heuristics to extract surrounding identifiers.
Embedding raw code without context leads to false positives when functions use common verbs or variables like Search or Init.
Prepending the file path, language, and chunk type/name gives the embedding input explicit context. Repository and signature fields are not added to this header; a signature may already appear in the raw code.
Dense vector embeddings excel at semantic similarity (e.g. matching "how does chunking work?" with ChunkFile), but struggle with exact symbol navigation (e.g. "SearchWithTimings"). BM25 complements them with identifier and keyword matches. RRF fuses them without needing fragile score calibration:
Ollama 768d vector captures natural concepts, high-level intent, and synonyms.
Split identifier tokens, preserved full identifiers, and additive stems support keyword matching.
Lookup and fusion run inside Qdrant in one query RPC; the CLI still handles encoding and transport.
Illustrative candidate lists: dense favors a conceptual overview; sparse favors the exact ChunkFile symbol. Switch modes to compare the resulting order.
| Candidate | Dense position | Sparse position | RRF calculation | Result rank |
|---|
Qdrant uses zero-based positions: first = 0. With this project's k=60, a first-place contribution is 1/60. An absent candidate contributes 0. Qdrant's formula ↗
Changed runs re-chunk the selected repository/language scope and refresh BM25 statistics and complete-point upserts. Dense vectors are reused from cache when exact enriched input and representation/model identity match; only cache misses call Ollama. Dense reuse does not make every indexing stage proportional to the edit.
Each file's SHA-256 is compared with Qdrant payloads. If hashes and index version all match, indexing is a no-op.
The CLI's representation includes chunk settings and embedder identity; Ollama supplies a model digest. Cached vectors are validated before reuse. Declaration identity distinguishes same-name Go methods; version migration removes old IDs.
index --watch debounces fsnotify events and re-runs the full index pipeline — not a per-file embed-only daemon.
A collection writer lock prevents overlapping local indexers. Durable markers record incomplete or failed runs; end-of-run source verification rejects a changed source snapshot. Writes remain visible in place, and full retry-versus-clean-rebuild acceptance is still open. Inspect run state ↗ and dense cache ↗.
Measured via ragcodepilot eval --mode hybrid — run —. Inspect saved retrieval report ↗. Self-dogfood on this repo, not a public IR benchmark. Retrieval metrics do not measure answer correctness or generation latency.
The saved post-merge recheck used source —, not the October implementation-review date. No labels or thresholds were changed to hide known failures.
chi retrieval report ↗ · Point survival, coverage, and failures ↗ · Run provenance ↗
Probe dated —: —; —. The clean corpus had one file/two chunks; the warm corpus had two files/four chunks. This is not a controlled speedup claim, corpus benchmark, or capacity result. Sparse vectors and upserts still covered every current chunk.
Generation is a separate cost: the saved — from — with --answer-limit 5 measured — p50 and — p95 for generation. This older, different workload is not an end-to-end latency comparison with the post-merge retrieval run. Inspect saved answer report ↗.
—
| Query String | Type | Top Returned File | Outcome (Hybrid RRF) |
|---|
Install Go —, Git, Docker with Compose, and Ollama first. Start Docker and the Ollama app/service. Commands below run in your terminal, not in this website.
If you already have this repository, open its root directory and skip cloning.
git clone https://github.com/thuyvy3110/ragcodepilot.git
cd ragcodepilotQdrant runs in Docker; Ollama runs on the host. If Ollama is not already running, start ollama serve in a separate terminal. Downloads require internet access.
docker compose up -d qdrant
ollama pull nomic-embed-text
go run ./cmd/ragcodepilot versionWait for indexing to finish before searching. This creates the default code_chunks collection using Go source files.
go run ./cmd/ragcodepilot index --language go .Hybrid search returns ranked source chunks, file paths, and line ranges. It does not need a generative model.
go run ./cmd/ragcodepilot search "how does chunking work?"Download the additional model, then use --answer. The first call can take longer while the model loads. Inspect its source citations to judge the answer.
ollama pull qwen2.5-coder:7b
go run ./cmd/ragcodepilot search --answer "how does chunking work?"ollama serve. Run ollama list to check downloaded models.docker compose ps and docker compose logs qdrant. The CLI uses port 6334.Switch tabs for abbreviated, illustrative output. These examples do not execute commands or measure performance. Run the copied commands locally after setup.