### **Structural Code Intelligence for AI Agents β MCP Server + Knowledge Graph + Semantic Search**
[](https://github.com/Muvon/octocode/actions/workflows/ci.yml)
[](https://github.com/Muvon/octocode/actions/workflows/ci.yml)
[](https://crates.io/crates/octocode)
[](https://github.com/Muvon/octocode/stargazers)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.rust-lang.org)
[](https://github.com/Muvon/octocode/releases)
**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](#-quick-start) β’ [π€ MCP Integration](#-mcp-server-integration) β’ [π Documentation](#-documentation) β’ [π Website](https://octocode.muvon.io)
---
## π€ 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:
```
You: "Where is authentication handled?"
AI: *searches your codebase* "Authentication is in src/middleware/auth.rs,
which imports jwt.rs for token validation and calls user_store.rs for lookup."
You: "What files depend on the payment module?"
AI: *queries knowledge graph* "src/api/handlers/payment.rs imports payment/mod.rs,
which is also used by src/workers/refund.rs and src/cron/billing.rs"
You: "Find every call site of this function"
AI: *uses LSP find-references* "process_payment() is called from 4 places:
checkout.rs:87, refund.rs:134, billing.rs:56, and tests/payment_test.rs:23"
```
## π€ 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*.
```
# Semantic search finds the right code
octocode search "authentication middleware"
β src/middleware/auth.rs β Similarity: 0.9234
# The GraphRAG CLI queries the optional persisted graph
octocode config --graphrag-enabled true
octocode index
octocode graphrag get-relationships --node-id src/middleware/auth.rs
Outgoing:
imports β jwt (src/auth/jwt.rs): token validation logic
calls β user_store (src/db/user_store.rs): user lookup by token
Incoming:
imports β router (src/router.rs): wires auth into the request pipeline
```
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
```
Current Source β Tree-sitter AST β Live Symbol Graph βββββββββββββββ MCP `graphrag`
β β
Indexed Code β Embeddings + Optional LLM β Persisted File Enrichment ββββββ
```
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/`](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.
The benchmark also flags what _doesn't_ help here (full 6-variant matrix in [`benchmark/RESULTS.md`](benchmark/RESULTS.md)): a **generic** local cross-encoder reranker (`bge-reranker-base`) actually **regressed** results (Hit@5 0.732 β 0.598) β code retrieval needs a _code-aware_ reranker (e.g. `voyage:rerank-2.5`), not an off-the-shelf one.
```bash
git clone https://github.com/Muvon/octocode && cd octocode
git worktree add /tmp/corpus b1771ba # pin the corpus to the ground-truth commit
CORPUS=/tmp/corpus python3 benchmark/run_matrix.py # set OCTO_BIN to use a custom binary
```
See [benchmark/README.md](benchmark/README.md) for methodology and metric definitions.
## π Quick Start
### 1. Install
```bash
# Universal installer (Linux, macOS, Windows)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
# macOS with Homebrew
brew install muvon/tap/octocode
```