Give your AI agent the blueprint, not just the manual

What it does

Octocode is a single Rust binary that indexes your project and exposes it to AI assistants via a built-in MCP server. Claude, Cursor, or Windsurf can then run semantic search, view file signatures, traverse a dependency graph, and — if you wire in a language server — do go-to-definition and find-references. It’s local-first, so your code stays on your machine.

The interesting bit

The graph isn’t built from embeddings or an LLM: tree-sitter parses the AST and extracts deterministic imports, calls, extends, and implements relationships directly from source. That graph works even with indexing disabled, so agents get structural navigation for free. Embeddings and optional LLM descriptions are a separate, overlay layer.

Key highlights

• Hybrid retrieval: dense vectors + BM25, with a reproducible 127-query benchmark on its own source (pinned commit, no API key needed)
• Benchmark finding worth stealing: tilting RRF fusion toward keywords lifted Hit@5 by 22% — code’s exact identifiers reward BM25
• A generic off-the-shelf reranker actually regressed results; code retrieval needs a code-aware reranker
• structural_search does AST pattern matching — e.g. hunt down every .unwrap() call
• Multiple embedding providers supported, but local FastEmbed is the default with no key required

Caveats

• LSP tools (goto-definition, find-references, hover) require explicitly starting the server with a language server — they’re not free
• The headline benchmark numbers are measured on octocode’s own codebase, which is a friendly corpus for a code-search tool

Verdict

If you use Claude Code, Cursor, or any MCP client on a real codebase, this is one of the more thoughtful takes on code retrieval — the AST-first graph is the part worth watching. If you just want library docs for your AI, doc-lookup tools are simpler.