nova-rag
Free and open source (MIT). If nova-rag saves you time, a star is the best thanks.
Ask questions about code in plain language. Get answers with full context.
The only MCP server that combines semantic search with code graph intelligence. Other code graph servers require exact symbol names. nova-rag understands natural language.
You: "where is payment processing?"
nova-rag: processStripeWebhook() in payments/webhook.py:34
Callers: handle_checkout, subscription_renewal
Callees: update_order_status, send_receipt
PaymentService class in payments/service.py:12
Callers: checkout_endpoint, admin_refund
100% local. No API keys. No data leaves your machine.
Installation
⏱️ First install downloads ~500MB (torch, faiss, sentence-transformers). Expect 2–5 minutes on a good connection, longer on slow networks. All commands below pass
-v/--verboseso pip shows live progress — if the terminal looks quiet for more than ~30 s duringCollecting torch, it's just a big download, not a hang.
macOS
# 1. Install Python + pipx (if you don't have them)
brew install python@3.12 pipx
pipx ensurepath
# 2. Restart terminal, then install nova-rag (live logs)
pipx install nova-rag --verbose
# 3. Connect to Claude Code (one time, works for all projects)
claude mcp add nova-rag -- ~/.local/bin/nova-rag
Windows
- Install Python from python.org — check "Add to PATH"
- Open PowerShell:
pip install -v nova-rag
claude mcp add nova-rag -- nova-rag
The -v flag makes pip print every download and build step so you can
watch progress in real time.
Linux
# Ubuntu/Debian
sudo apt install python3 python3-pip
pip3 install -v nova-rag
# If "externally-managed-environment" error:
pipx install nova-rag --verbose && pipx ensurepath
claude mcp add nova-rag -- ~/.local/bin/nova-rag
Update: pipx upgrade nova-rag --verbose (or pip install -v --upgrade nova-rag)
Uninstall: pipx uninstall nova-rag and rm -rf ~/.nova-rag
⚠️ pipx upgrade bug (macOS): Some versions of pipx (e.g. 1.11.0) fail to upgrade packages with hyphens in the name and show:
Error: 'nova-rag' looks like a path. Expected the name of an installed package.If this happens, use force reinstall instead — it's equivalent to upgrade:pipx install git+https://github.com/Miro96/nova-rag.git --force --verbose
⚠️ If
pipx uninstallalso fails with the same path error, remove manually:rm -rf ~/.local/pipx/venvs/nova-rag rm ~/.local/bin/nova-rag
Usage — Just Ask
Once connected, ask Claude Code anything. nova-rag auto-indexes on first query.
| You ask | What happens |
|---|---|
| "where is authentication handled?" | Semantic search — finds code by meaning |
| "who calls handleAuth?" | Code graph — shows all callers |
| "what does processData call?" | Code graph — shows all callees |
| "who imports psycopg2?" | Import graph — shows all importers |
| "find unused functions" | Dead code detection |
| "impact of changing validate?" | Blast radius — affected files, tests, risk |
| "class hierarchy of UserService" | Inheritance tree — parents and children |
| "what changed this week?" | Git intelligence — changes mapped to code graph |
Monorepo Support
nova-rag auto-detects sub-projects in monorepos:
mycompany/ ← open Claude Code here
├── api-core/ (*.csproj) ← detected: backend, csharp
├── web-app/ (package.json with next) ← detected: frontend, typescript
└── shared-lib/ (pyproject.toml) ← detected: backend, python
> "backend auth handling" → searches only api-core (auto-detected)
> "login page component" → searches only web-app (auto-detected)
> "who calls UserService?" → searches all projects
> code_search("auth", project="api-core") → explicit filter
| Tool | What it does |
|---|---|
rag_projects |
List all detected sub-projects with type/language/status |
rag_projects_add |
Explicitly add a project to the workspace |
rag_projects_remove |
Remove a project from the workspace |
Detected by marker files: *.csproj, package.json, go.mod, Cargo.toml, pyproject.toml, Gemfile, pom.xml, composer.json, Package.swift, CMakeLists.txt.
How It Works
Hybrid Search (Vector + BM25)
Your query is processed two ways:
- Vector search — neural network finds semantically similar code (FAISS)
- Keyword search — exact word matching via SQLite FTS5 (BM25)
Merged via Reciprocal Rank Fusion: score = 1/(k + rank_vector) + 1/(k + rank_keyword)
| Query | Vector finds | Keyword finds | Combined |
|---|---|---|---|
| "error handling" | Exception handlers, try/catch | Code with "error" | Both, best first |
| "getUserById" | fetchUser (similar meaning) | Exact match | Exact match #1 |
| "database connection" | get_pool() | Nothing (wrong words) | Found via vector |
Code Graph
During indexing, tree-sitter extracts from every file:
- Symbols — function/class/method definitions
- Calls — who calls what
- Imports — module dependencies
- Inheritance — extends/implements relationships
This enables: callers, callees, importers, class hierarchy, dead code, impact analysis.
Search results automatically include callers/callees — no extra query needed.
Smart Router
One tool code_search handles everything. It reads your query and routes:
"where is error handling?" → semantic search
"who calls handleAuth?" → graph: callers
"what does process call?" → graph: callees
"who imports psycopg2?" → graph: importers
"dead code in src/" → dead code detection
"impact of changing validate" → impact analysis
"class hierarchy of User" → inheritance
"what changed this week?" → git intelligence
"backend auth" → monorepo: filter to backend projects
Indexing Pipeline
Source files → File Discovery (.gitignore, skip binaries/configs/docs)
→ ThreadPoolExecutor (8 threads)
├── Tree-sitter parse → chunks (functions, classes)
└── Graph extract → symbols, calls, imports, inheritance
→ Batch Embedding (sentence-transformers, local)
→ Storage (FAISS vectors + SQLite FTS5 + graph tables)
First index: 30-120s. Subsequent: incremental (only changed files). File watcher auto-reindexes.
All Tools
| Tool | Description |
|---|---|
code_search |
Smart router — one tool for everything (recommended) |
rag_search |
Direct hybrid search |
rag_graph |
Navigate code graph: callers/callees/importers/hierarchy |
rag_impact |
Blast radius: what breaks if you change a function |
rag_deadcode |
Find unused functions |
rag_git_changes |
Recent git changes mapped to code graph |
rag_source |
Get full source code by chunk ID (O(1) retrieval) |
rag_index |
Index/reindex a project |
rag_status |
Check index status |
rag_watch |
Start file watcher |
rag_projects |
List sub-projects in workspace |
rag_projects_add |
Add a project to workspace |
rag_projects_remove |
Remove a project from workspace |
Tool parameters
code_search — query (str), path (str), project (str), top_k (int=10), path_filter (str), language (str)
rag_graph — name (str), path (str), direction ("callers"/"callees"/"both"/"importers"/"hierarchy"), depth (int=1)
rag_impact — name (str), path (str)
rag_deadcode — path (str), path_filter (str)
rag_git_changes — path (str), since (str="1 week ago"), path_filter (str)
rag_source — chunk_id (int), path (str)
rag_projects_add — project_path (str), name (str), path (str)
rag_projects_remove — name (str), path (str)
Supported Languages (14)
| Language | Chunks | Graph |
|---|---|---|
| Python, TypeScript/TSX, JavaScript/JSX | functions, classes | calls, imports, inheritance |
| C#, Java, Kotlin, Scala | methods, classes, interfaces | calls, imports, inheritance |
| Go, Rust, Swift | functions, structs, traits | calls, imports |
| C, C++ | functions, structs | calls, #include |
| PHP | functions, classes, traits | calls, imports |
| Ruby | methods, classes, modules | calls, require |
| Other files | sliding window (60 lines) | — |
Configuration
| Variable | Default | Description |
|---|---|---|
NOVA_RAG_MODEL |
all-MiniLM-L6-v2 |
Embedding model |
NOVA_RAG_CHUNK_SIZE |
60 |
Max lines per chunk |
NOVA_RAG_BATCH_SIZE |
64 |
Embedding batch size |
NOVA_RAG_DATA_DIR |
~/.nova-rag |
Index storage |
Use with CLAUDE.md
Add to your project's CLAUDE.md:
## Code Search (nova-rag)
Prefer `code_search` over Grep for questions about the codebase:
- "where is payment processing?" → finds functions with full context
- "who calls handleAuth?" → shows all call sites
- "dead code in src/" → finds unused functions
Search results include callers/callees — use them for full context.
For exact string matches (TODOs, error messages), use Grep.
Troubleshooting
| Problem | Solution |
|---|---|
nova-rag: command not found |
Run source ~/.zshrc or use full path ~/.local/bin/nova-rag |
| First search is slow | Model (~80MB) downloads on first use. Cached after that |
| High memory (~400MB) | That's the embedding model. Use NOVA_RAG_MODEL=all-MiniLM-L12-v2 |
| Index stale | File watcher auto-updates. Force rebuild: rag_index(force=true) |
| Large response warning | Normal for big projects. Claude Code handles it via file fallback |
Development
git clone https://github.com/Miro96/nova-rag.git
cd nova-rag
pip install -e ".[dev]"
pytest tests/ -v # 129 tests
Project structure
src/nova_rag/
├── server.py MCP server, 14 tools
├── searcher.py Smart router, hybrid search, graph queries, workspace search
├── workspace.py Monorepo detection, project management
├── indexer.py Multithreaded file processing + embedding
├── chunker.py Tree-sitter AST parsing (14 languages)
├── graph.py Code graph: symbols, calls, imports, inheritance
├── git_intel.py Git change intelligence
├── store.py FAISS + SQLite (FTS5 + graph tables)
├── watcher.py File watcher for auto re-indexing
└── config.py Environment-based configuration
Contributing
See CONTRIBUTING.md. To add a new language, update chunker.py + graph.py + pyproject.toml.
License
MIT — see LICENSE.
Metadata
Release files for nova-rag 0.3.9
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| nova_rag-0.3.9.tar.gz | 60.6 kB | With provenance | Details for nova_rag-0.3.9.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| nova_rag-0.3.9-py3-none-any.whl | Python 3 | none | any | Details for nova_rag-0.3.9-py3-none-any.whl |
Total release size: 107.5 kB
Release files / nova_rag-0.3.9.tar.gz
| Download URL | nova_rag-0.3.9.tar.gz |
|---|---|
| Size | 60.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0a2f3166e415790cd1fd41af16379b03aea17f0c51d1aa325e3f70443154d9f5
|
|
BLAKE2b-256 checksum How to use checksums |
3a0526aabf6118febae5bcb4ba5ee3fcb823318ce6f6892ac3d6e556750dcb55
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logRelease files / nova_rag-0.3.9-py3-none-any.whl
| Download URL | nova_rag-0.3.9-py3-none-any.whl |
|---|---|
| Size | 46.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d382d6287cad40867daa1e221687eb8b9cbed1b7370e2c9e519c07ed6c684e39
|
|
BLAKE2b-256 checksum How to use checksums |
55b8b963334c44a7038cd7248e599487ab150c4611c3310b5e8c010eb412934b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logSecurity for nova-rag 0.3.9
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for nova_rag-0.3.9.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Apr 14, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.