Skip to main content

nova-rag

License: MIT Python 3.11+ MCP Tests Languages Free

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 / --verbose so pip shows live progress — if the terminal looks quiet for more than ~30 s during Collecting 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
  1. Install Python from python.org — check "Add to PATH"
  2. 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 uninstall also 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)

Source distribution for nova-rag 0.3.9
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)

Table of built distributions (wheels) for nova-rag 0.3.9
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page