Muvon/octocode

Octocode – Structural Code Intelligence for AI Agents

What it is – Octocode is an open‑source Rust tool that turns a codebase into a live, queryable knowledge graph. It ships a built‑in MCP server (the Model‑Center‑Protocol used by Claude Desktop, Cursor, Windsurf, etc.) so AI assistants can search, navigate, and reason over your project's structure just like a human would.

Why it matters – Typical Retrieval‑Augmented Generation (RAG) treats source files as flat text chunks, losing the relationships between imports, function calls, inheritance, and module boundaries. Octocode extracts an AST‑based symbol graph with deterministic edges (imports, calls, extends, implements, …) and exposes that graph, plus semantic search, to any MCP‑compatible agent. The result is code‑aware answers such as “where is authentication handled?” or “what files depend on the payment module?” without the AI having to guess from keyword matches.

---

Core capabilities

Feature	What you get
Semantic search	Natural‑language queries return the most relevant files using a hybrid of BM25 keyword matching and vector embeddings (Voyage, OpenAI, Jina, etc.).
Live AST graph	Tree‑sitter parses the current source tree into nodes (files, symbols) and edges (imports, calls, …) that are always up‑to‑date – no separate index required.
GraphRAG (optional)	An optional persisted graph adds LLM‑generated descriptions and broader architectural relationships on top of the deterministic graph.
LSP integration	When started with --with-lsp, the server forwards goto‑definition, find‑references, hover, completion, etc., using your language server (e.g., rust‑analyzer).
Structural search	AST pattern matching lets you locate specific code patterns (e.g., all .unwrap() calls).
Multi‑language support	16 languages are parsed out‑of‑the‑box (Rust, Python, TypeScript/JS, Go, PHP, C++, Ruby, Elixir, Java, Swift, Svelte, Lua, CSS, JSON, Bash, Markdown).
Local‑first & privacy‑first	Embeddings can be generated locally via fastembed; cloud providers are optional and only see the chunks you explicitly send.

---

How it works (high‑level flow)

1. Tree‑sitter parses each source file → nodes for files, functions, classes, etc.
2. Live symbol graph is built from those nodes with deterministic edges (contains, imports, calls, …).
3. Optional indexing: embeddings are computed for each file (or symbol) and stored; an optional LLM can add textual descriptions.
4. MCP server exposes RPC tools (semantic_search, view_signatures, graphrag, structural_search, LSP helpers) that AI agents call.
5. Hybrid retrieval combines BM25 keyword scores with vector similarity (RRF fusion) to rank results.

---

Quick start (install → index → query)

# Install (curl installer, Homebrew, or cargo)
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh
# or: brew install muvon/tap/octocode
# or: cargo install octocode

# Set an embedding provider (Voyage AI key shown as example)
export VOYAGE_API_KEY="your-key"

# Index a project
cd /path/to/your/project
octocode index   # processes every file and builds the live graph

# Natural‑language search
octocode search "authentication middleware"

---

Connecting an AI assistant (MCP client)

Add a server entry to the client’s mcpServers config, e.g. for Claude Desktop:

{
  "mcpServers": {
    "octocode": {
      "command": "octocode",
      "args": ["mcp", "--path", "/path/to/your/project"]
    }
  }
}

The assistant can now call tools like semantic_search or graphrag and answer code‑base questions with concrete locations and call‑graphs.

Retrieval quality (benchmark)

Octocode ships a reproducible benchmark (127 code‑search queries) run on its own source tree. With a simple hybrid (BM25 0.3 + vector 0.7) it achieves:

• Hit@5 = 0.732
• Hit@10 = 0.835
• MRR = 0.572
• Recall@10 = 0.807 A keyword‑heavy weighting improves Hit@5 by +22 % over dense‑only retrieval. The benchmark also shows that a generic code reranker (bge‑reranker‑base) hurts performance, indicating the need for code‑specific rerankers.

---

Who might use it

• Developers who want their LLM‑powered assistants (Claude, Cursor, etc.) to understand the actual architecture of a repository.
• Teams building internal AI agents that need reliable, privacy‑preserving code navigation.
• Tool makers looking for a ready‑made MCP server that provides LSP‑level precision without re‑implementing AST parsing.

---

License & community

• License: Apache 2.0 (permissive, commercial‑friendly).
• Repo activity: CI badge, coverage badge, releases on crates.io, and a growing star count.
• Support: GitHub Issues, Discussions, and a contact email (opensource@muvon.io).

---

Bottom line: Octocode is a real, production‑grade Rust project that gives AI agents a structural, graph‑based view of your code, enabling precise, context‑aware assistance while keeping everything local and under your control.