Octocode – Structural Code Intelligence for AI Agents Clone: git clone https://github.com/moses-y/octocode

The Problem

AI assistants can search text but lack a model of code structure. They cannot resolve imports, find call sites, or understand module dependencies, so queries about “where is authentication handled?” or “which files depend on the payment module?” return noisy or incomplete results.

What This Does

Octocode builds a live knowledge graph from a Rust project using tree‑sitter.

  • src/indexer/* parses files, extracts symbols, imports, calls, and inheritance.
  • src/commands/* expose a CLI that drives the indexer, runs semantic search (octocode search), and exposes GraphRAG queries (octocode graphrag …).
  • src/mcp/* implements an MCP server (graphrag.rs, logging.rs) that exposes the graph over HTTP for Claude, Cursor, or any MCP client.
  • src/llm/mod.rs supplies a lightweight LLM wrapper that can generate embeddings for search without storing them locally.

The result is a navigable graph: go‑to‑definition, find‑references, semantic search, and code signatures all in a single binary.

How It Is Wired

  • Entry point: src/main.rs parses CLI arguments via src/commands/mod.rs.
  • Indexing flow: octocode index → src/indexer/mod.rs → src/indexer/file_processor.rs → src/indexer/signature_extractor.rs → src/embedding/mod.rs.
  • Graph exposure: src/mcp/graphrag.rs loads the graph into memory and serves it through the MCP protocol defined in src/mcp/lsp/protocol.rs.
  • LSP integration: src/mcp/lsp/client.rs implements the client side; src/mcp/lsp/provider.rs forwards LSP requests to the graph.
  • Persistence: optional GraphRAG database lives in src/indexer/graphrag/database.rs; it writes to SQLite and can be queried via octocode graphrag ….
  • External side effects: the only I/O is reading source files (src/indexer/file_utils.rs) and writing the SQLite DB (src/indexer/graphrag/database.rs). No network writes except the MCP server.

How To Use It

Setup

# Build the binary
cargo build --release

# Optional: install the CLI
install.sh  # copies binary to ~/.cargo/bin

Configuration

  • Edit config-templates/default.toml to create octocode.toml.
  • Override with environment variables like OCTOCODE_DATA_DIR.

Running the MCP server

# Start the server on default port 8080
cargo run --release -- mcp

Indexing the codebase

# Build the graph in memory and persist to DB
cargo run --release -- index

Semantic search

cargo run --release -- search "authentication middleware"

GraphRAG query

cargo run --release -- graphrag get-relationships --node-id src/middleware/auth.rs

Real‑World Use

A continuous‑integration pipeline can run octocode index before every merge, then expose the MCP endpoint. A custom LLM in a policy engine can query the graph to enforce code‑ownership rules:

{ "role": "owner", "node": "src/api/handlers/payment.rs" }

Code Health & Issues

  • Tests: 81 test files under src/*_tests.rs.
  • CI: GitHub Actions in .github/workflows/*.
  • License: Apache‑2.0.
  • No measured analysis: Static checkers (clippy, cargo audit) not present; no automated security scan reported.
  • Missing docs: doc/ contains most high‑level docs but no detailed API reference for the MCP protocol.
  • Build artifacts: Cargo.lock ensures reproducible builds.

The Bottom Line

Octocode delivers a focused, single‑binary solution for AI agents that need structural insight into a Rust codebase. The architecture is clear, the build pipeline is straightforward, and the MCP server makes integration painless. The main caveats are lack of automated security checks and limited API documentation. It is well suited for teams that already use Rust and want an out‑of‑the‑box knowledge graph for LLM‑powered tooling.