muvon/octocode

**Give your AI assistant a brain for your codebase.** Octocode transforms your project into a navigable knowledge graph that Claude, Cursor, and other AI agents can search, understand, and navigate.
🚀 Quick Start • 🤖 MCP Integration • 📖 Documentation • 🌐 Website
---
🤖 Built for AI Agents
**The Problem:** AI assistants are blind to your codebase. They can't search your files, understand dependencies, or remember context across sessions.
**The Solution:** Octocode's MCP server gives AI agents:
- 🔍 **Semantic search** — Find code by meaning, not keywords
- 🕸️ **Knowledge graph** — Navigate imports, calls, and dependencies
- 📝 **Code signatures** — View structure without reading entire files
- 🧭 **LSP precision** — Go-to-definition, find-references, and hover docs via your language server
**Works with:** Claude Desktop • Cursor • Windsurf • Any MCP-compatible AI
Now your AI assistant can:
🤔 Why Octocode?
**Standard RAG treats your code as flat text chunks.** It finds similar-sounding snippets but has no idea that auth_middleware.rs imports jwt.rs, calls user_store.rs, and is wired into router.rs. Octocode understands *structure*.
Octocode uses **tree-sitter AST parsing** to build a live graph of files, symbols, imports, calls, inheritance, and implementations. The MCP graphrag tool builds this graph lazily from the current source tree, without an index, embeddings, or an LLM. Optional indexed GraphRAG adds semantic file discovery, descriptions, and broader architectural relationships.
🔬 How It Works
1. **Live AST Graph** — tree-sitter extracts file and symbol nodes plus deterministic contains, imports, calls, extends, and implements relationships directly from current source
2. **Always-on Graph Navigation** — MCP graph lookup, relationship traversal, path finding, and overview work with [graphrag].enabled = false
3. **Optional Enrichment** — enabling indexed GraphRAG overlays semantic file matches, LLM descriptions, and broader file-level architectural relationships; symbols are never embedded or LLM-generated
4. **Hybrid Search** — semantic similarity + BM25 full-text search + reranking handles meaning-based code retrieval separately
5. **MCP Server** — exposes semantic_search, view_signatures, graphrag, and structural_search to any MCP-compatible client
✨ What Makes It Different
| | Standard RAG | Doc Lookup Tools | **Octocode** |
|---|---|---|---|
| **Indexes** | Text chunks | External library docs | Your codebase structure (AST) |
| **Understands** | Similar text | API specs & usage | Functions, imports, dependencies |
| **Cross-file** | No | No | Yes — navigates the dependency graph |
| **Relationships** | No | No | imports, calls, implements, extends... |
| **AI integration** | Varies | MCP | Native MCP server + LSP |
> **Doc tools give AI the manual for libraries you use. Octocode gives AI the blueprint of how you put them together.**
**Built with Rust** for performance. **Local-first** for privacy. **Open source** (Apache 2.0) for transparency.
📊 Retrieval Quality
Octocode ships a **reproducible retrieval benchmark** (benchmark/): 127 curated code-search queries with line-range ground truth, run against octocode's own source (pinned at b1771ba so annotations never drift). The numbers below use a **fully local, no-API-key** stack — jina-embeddings-v2-base-code via fastembed, **no reranker** — so they are a floor, not a ceiling:
| Config | Hit@5 | Hit@10 | MRR | NDCG@10 | Recall@10 |
|---|---|---|---|---|---|
| Dense vector only | 0.598 | 0.717 | 0.485 | 0.528 | 0.671 |
| Hybrid, default RRF weights (0.7/0.3) | 0.598 | 0.717 | 0.485 | 0.528 | 0.671 |
| **Hybrid, keyword-tuned (0.3/0.7)** | **0.732** | **0.835** | **0.572** | **0.620** | **0.807** |
Tilting RRF fusion toward the BM25/keyword signal — which carries disproportionate weight for code's exact identifiers — lifts **Hit@5 by +22%** and **Recall@10 by +20%** at zero added cost.