octocode

Structural Code Intelligence for AI Agents — MCP Server + Knowledge Graph + Semantic Search

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
• 🧠 Persistent memory — Remember decisions across conversations

Works with: Claude Desktop • Cursor • Windsurf • Any MCP-compatible AI

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

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: "Remember this bug fix for future reference"
AI: *stores in memory* "Got it. I'll remember this authentication bypass fix
    and apply similar patterns when reviewing security code."

🤔 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.923

# GraphRAG reveals the full dependency chain
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 extract real symbols (functions, imports, dependencies), builds a GraphRAG knowledge graph of relationships between files, and exposes everything via MCP — so AI tools can navigate your project architecture, not just search it.

🔬 How It Works

Source Code → Tree-sitter AST → Symbols & Relationships → Knowledge Graph
                                        ↓
                    Embeddings + Hybrid Search + Reranking → MCP Server

1. AST Parsing — tree-sitter extracts real code symbols (functions, classes, imports), not arbitrary text chunks
2. Knowledge Graph — GraphRAG maps relationships between files: imports, calls, implements, extends, configures, and 9 more types — each with importance weighting
3. Hybrid Search — semantic similarity + BM25 full-text search + reranking — not just vector embeddings
4. MCP Server — exposes semantic_search, view_signatures, and graphrag tools to any MCP-compatible client

✨ What Makes It Different

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:

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): 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.

git worktree add /tmp/corpus b1771ba        # pin the corpus to the ground-truth commit
CORPUS=/tmp/corpus python3 benchmark/run_matrix.py

See benchmark/README.md for methodology and metric definitions.

🚀 Quick Start

1. Install

# 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

# Cargo (build from source)
cargo install --git https://github.com/Muvon/octocode

# Download binary from releases
# https://github.com/Muvon/octocode/releases

See Installation Guide for platform-specific instructions.

2. Set Up API Keys

# Required: Embedding provider (Voyage AI has 200M free tokens/month)
export VOYAGE_API_KEY="your-voyage-api-key"

# Optional: LLM for commit messages, code review
export OPENROUTER_API_KEY="your-openrouter-api-key"

Get your Voyage API key: voyageai.com (free tier available)

Octocode supports multiple embedding providers:

# OpenAI
export OPENAI_API_KEY="your-key"
octocode config --code-embedding-model "openai:text-embedding-3-small"

# Jina AI
export JINA_API_KEY="your-key"
octocode config --code-embedding-model "jina:jina-embeddings-v3"

# Google
export GOOGLE_API_KEY="your-key"
octocode config --code-embedding-model "google:text-embedding-005"

See API Keys guide for all supported providers.

3. Index Your Codebase

cd /your/project
octocode index
# → Indexed 12,847 blocks across 342 files

4. Search Your Code

# Natural language search
octocode search "authentication middleware"

# Multi-query for broader results
octocode search "auth" "middleware" "session"

# Filter by language
octocode search "database connection pool" --lang rust

# Search commit history
octocode search "authentication refactor" --mode commits

5. Connect Your AI Assistant

Add to your MCP client config (Claude Desktop, Cursor, Windsurf):

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

Done! Your AI assistant now understands your codebase structure.

🔌 MCP Server Integration

Octocode includes a built-in MCP server that exposes your codebase as tools to AI assistants. This is the primary way to use Octocode — give your AI assistant direct access to search and navigate your code.

Available Tools

Conversational AI Examples

Once connected, your AI assistant can answer questions about your codebase:

You: "Where is user authentication implemented?"
AI: *uses semantic_search* "Found in src/auth/login.rs. The authenticate() function
    validates credentials against the database, generates a JWT token, and stores
    the session in Redis."

You: "What files depend on the payment module?"
AI: *uses graphrag* "src/api/handlers/