Skip to content

What is CodeNavi

CodeNavi is a self-hosted code search and intelligence server for AI coding agents — search that understands meaning, not just matches, over private codebases, running entirely on hardware you control. It indexes your code (plus documentation and, optionally, crawled web pages) and serves ranked, reranked results over the Model Context Protocol (MCP) — ask "where do we handle token expiration?" and get the code that does it, whatever it happens to be named, instead of grepping blindly for strings. It is also a security layer for AI-assisted development: a built-in scanner redacts secrets and PII at indexing time and catches prompt-injection content — in code, documents and crawled pages — before it ever reaches your agent's context. A built-in web UI gives humans the same engine.

Why it exists: some codebases can't leave the building — client work, IP-sensitive systems, regulated environments. CodeNavi was built so AI coding agents can work on that code anyway, with the whole retrieval stack on hardware you control.

And the results are measured, not promised: agents burn most of their context window reading files to find things; CodeNavi answers "where does X happen?" with the five chunks that matter — 96/100 retrieval quality and ~80% context-token savings on the published suite, honest misses included. See Search quality.

Zero data egress by default. Indexing, search and reranking run local end-to-end; chat can stay local too (Ollama, LM Studio, vLLM). A cloud LLM is an explicit opt-in, never a requirement.

  • Core concepts

    The five-minute mental model — indexes, tools, codebases — that everything else builds on.

    Learn the basics

  • Search quality

    96/100 retrieval quality, ~80% token savings — measured, published, misses included.

    The numbers

  • Set up CodeNavi

    Connected install on Linux, macOS, or Windows — download, index, first search.

    Connected setup

  • Air-gapped install

    Deploy from the offline bundle on a network that never touches the internet.

    Air-gapped setup

  • Connect your agent

    Claude Code, Codex CLI, Antigravity, OpenCode, Pi, VS Code, Zed, and more — over MCP.

    Integration guides

  • API & CLI reference

    Every MCP tool, REST endpoint, and codenavi CLI command, with arguments and examples.

    Reference

  • Web UI

    Nine screens for humans — search, graph explorer, security, wiki — at :8765/ui.

    Web UI guide

  • Security & compliance

    The scanner, quarantine and redaction model, signed supply chain, and framework fit.

    Security model

  • Operate

    Updates, team servers, observability, webhooks — and what to do when something breaks.

    Updating CodeNavi

Who it's for

  • Teams whose codebase is the time sink — monorepos, fragmented microservices, legacy systems (PHP, Perl/CGI and 13 more languages) where "finding how things work" costs humans and agents alike more than writing the change does.
  • Organizations where sending source code to a third-party API is a non-starter — regulated industries, IP-sensitive code, air-gapped networks. CodeNavi installs, indexes, and then fades into the background as infrastructure your agent queries all day — nothing leaves the box, the compliance evidence ships built in, and the framework fit — GDPR to FedRAMP — is written down for your questionnaire.

What it does

Search & retrieval

  • Semantic code search — meaning-based retrieval powered by Buric-E4B, CodeNavi's own code-specialized embedding model (2560d), with cross-encoder reranking on top. Vector-first by design (it outperformed hybrid ranking on our benchmarks), with a keyword fallback to round out edge cases. Results are tagged [code], [doc], or [web] so you always know the source.
  • Exact & structural lookups — grep_search (reads the live filesystem, so negatives are trustworthy without reindexing), symbol_search, file_search, find_references, directory listings, and chunked file reads.
  • Call-graph intelligence — a precomputed relations sidecar powers find_callers (actual call sites, multi-hop), impact_analysis (blast radius before a refactor, hub symbols flagged by centrality), diff_impact (what a diff touches downstream), and graph_neighborhood (a bounded caller/callee sub-graph, rendered interactively in the Graph screen).
  • Multi-codebase — one server indexes many repositories. Scope per call (codebase=NAME), per endpoint (/mcp/{codebase}), or via a default; list_codebases shows what's indexed.

Knowledge & chat

  • Grounded chat — natural-language Q&A over your indexed code, docs, and crawled pages. The server retrieves, feeds a configurable LLM, and returns a cited answer. Self-hosted providers (Ollama, LM Studio, vLLM, AnythingLLM) keep everything local; cloud providers (Claude, OpenAI, Gemini, OpenRouter) are supported with an explicit warning before code leaves the box.
  • Documentation indexing — Markdown/text index automatically with code; PDF and DOCX ingest on demand from DOCS_DIR.
  • Docs Wiki — LLM-compiled knowledge pages synthesized across your documents, with per-claim source locators, staleness tracking, and input/output security gates. Readable in the UI and over MCP (wiki_pages / wiki_page).

Security (built in, one scanner across everything)

  • 48 detection rules — secrets (API keys, tokens, DSNs, private keys), prompt-injection patterns including doc-scoped prose-injection rules, and PII redaction on by default (payment cards Luhn-validated, IBANs mod-97-validated; an extended set — SSNs, emails, phones, public IPs — is opt-in). Secret-like values and PII are redacted at indexing time and never appear in search results or chat context.
  • Block + flag model — malicious files are quarantined and never indexed; suspicious chunks are indexed but tagged, and the retrieval gate keeps them out of results. Managed from the Security screen: allowlist with audit reasons, threat reports, a scan tester.
  • Compliance gap analysis — the Claude Code plugin ships /codenavi:compliance: an evidence-linked, rule-by-rule review against OWASP ASVS core, OWASP Top 10, or EU Cyber Resilience Act Annex I packs, every verdict cited to file:line, plus dependency-CVE reachability over your own code. See Compliance.
  • Signed supply chain — release images and update manifests are cosign-signed and the installer/updater verifies them fail-closed (unsigned artifacts are refused unless you explicitly override), and every release ships a CycloneDX SBOM. See the Security model.
  • Framework fit — how a self-hosted, zero-egress deployment answers GDPR, SOC 2 / ISO 27001, HIPAA, PCI DSS, and FedRAMP questionnaires is mapped framework by framework — including what CodeNavi deliberately does not claim.

Operations

  • Fast incremental indexing — seconds for day-to-day changes; full rebuilds only when you ask. Reindexes are cancellable, never block search (double-buffered table swap), and report freshness on every query.
  • Web UI — nine screens (System, Index, Chat, Crawler, Search, Graph, Security, Wiki, Settings) served by the same container at :8765/ui. See the Web UI guide.
  • Web crawler (opt-in) — index your own sites/wikis with a safety scanner that structurally refuses destructive links; adds 8 crawler tools when enabled.
  • Everything else you'd expect — backup/restore snapshots, a search-feedback loop with demotion, query analytics, webhooks & script hooks, Prometheus metrics + a turnkey Grafana stack (observability), and a codenavi CLI that mirrors every MCP tool.

Works with your agent

CodeNavi speaks MCP over streamable HTTP — 33 tools (41 with the crawler) at http://localhost:8765/mcp. By default the server advertises an 11-tool core and loads the rest on demand via reveal_tools() (config.md). Bundled plugins wire up Claude Code, OpenAI Codex CLI, and Google Antigravity; guides cover Claude Desktop, OpenCode, Pi, VS Code, Zed, and AnythingLLM; a drop-in AGENTS.md covers everything else. Agents can self-discover the server via its card at GET /.well-known/agent-card.json.

Language support

15 languages chunk AST-aware via tree-sitter (functions, classes, methods split on semantic boundaries): PHP, JavaScript (incl. JSX), TypeScript (incl. TSX), Python, Bash, Go, Java, Ruby, Rust, C#, Fortran, Perl/CGI, Swift, Kotlin, Scala. SQL, templates, config, and prose formats index with dedicated or line-based chunking — the full matrix is in Supported languages.

Architecture

  MCP client (:8765/mcp[/{codebase}])      Browser (:8765/ui)
        |                                        |
  +-----------------------------------------------------------+
  |         CodeNavi (single container — Docker/Podman)       |
  |                                                           |
  |   FastMCP server — 33 tools (41 w/ crawler) + SPA at /ui  |
  |                                                           |
  |   +------------+   +------------+   +------------------+  |
  |   | Embedder   |   | LLM layer  |   | Security scanner |  |
  |   | Buric-E4B  |   | 8 providers|   | 48 rules, gates  |  |
  |   | 2560d +    |   | local or   |   | quarantine,      |  |
  |   | reranker   |   | cloud      |   | redaction        |  |
  |   +------------+   +------------+   +------------------+  |
  |                                                           |
  |   +---------------------+   +--------------------------+  |
  |   | LanceDB             |   | Sidecars                 |  |
  |   | code / doc / web    |   | call-graph relations,    |  |
  |   | chunks (2560d)      |   | feedback, chat, wiki     |  |
  |   +---------------------+   +--------------------------+  |
  |                                                           |
  |   Prometheus metrics (:9091)                              |
  +-----------------------------------------------------------+

Hardware, briefly

Indexing needs a GPU — NVIDIA (Linux, Windows 11 via Docker Desktop) or AMD ROCm (Linux); cards from 8 GiB up work via automatic batch/quantization tuning. A CPU-only host can still serve queries at full quality against an index built elsewhere — see cloud reindex for the supported pattern, and the setup guide's hardware tiers for the full picture (macOS included: install-mac.md). A vendor-assisted remote-embedder setup (one GPU box serving several installs) is available on request.

Where next

  1. Air-gapped setup or connected setup — install, index, first search.
  2. Setup guide — the full reference: hardware tiers, environment, multi-codebase config.
  3. Connect your agent — Claude Code first; the sidebar lists every other client.
  4. API reference — all 33 tools (41 with the crawler), REST endpoints, and the agent card.