Octocode
Semantic Search • Knowledge Graph • LSP Precision
Two-tier code intelligence for AI agents. A live AST graph — files, symbols, imports, calls, extends, implements — built by tree-sitter with zero indexing, always on. Layer in optional semantic search and LSP-precise go-to-definition when you need them. Retrieval quality is a published, reproducible benchmark, not a claim: Hit@10 0.992 on code search.
brew install muvon/tap/octocodeKey Features
Live AST Graph, Zero Indexing
Tree-sitter extracts file and symbol nodes plus deterministic contains, imports, calls, extends, and implements relationships directly from the current source tree. The graphrag MCP tool — graph lookup, relationship traversal, path finding — works with indexed GraphRAG fully disabled. No embeddings, no LLM, no index to go stale.
Optional Semantic Enrichment
Enable indexed GraphRAG and it overlays semantic file matches, LLM-written descriptions, and broader architectural relationships on top of the live graph — symbols themselves are never embedded or LLM-generated, so the deterministic core stays trustworthy either way.
LSP Precision On Top
Start with --with-lsp="rust-analyzer" (or any language server) and octocode adds lsp_goto_definition, lsp_find_references, lsp_hover, and workspace/document symbol search — compiler-verified answers, not AST heuristics, for the calls that have to be exact.
Structural Search
AST pattern matching finds code by shape, not text: every .unwrap() call, every new instantiation of a type, a specific syntax pattern regardless of formatting or variable names — the search grep and ripgrep cannot express.
Hybrid Search, Benchmarked in the Open
127 hand-annotated queries against octocode's own pinned source, fully reproducible (benchmark/run_matrix.py). Tilting RRF fusion toward the keyword signal lifts Hit@5 by +22% and Recall@10 by +20% at zero added cost — and the same report is honest that a generic reranker regressed results; only a code-aware one helps.
Multi-Query & Commit Search
search "auth" "middleware" "session" broadens a single query into several for wider recall in one call. --mode commits searches Git history semantically — find the change that introduced a pattern, not just the pattern itself.
Why Octocode?
grep and text search fail for conceptual queries.
Semantic search understands meaning: "HTTP middleware" finds auth handlers, rate limiters, and CORS config even when the code never uses that phrase.
Text-based tools guess at cross-file relationships and get them wrong.
graphrag builds the graph directly from tree-sitter AST — deterministic imports, calls, extends, implements — no LLM guessing, no embeddings required. Add --with-lsp for compiler-verified definitions and references on top.
"Better retrieval" is usually a marketing claim, not a number.
octocode publishes a reproducible retrieval benchmark against its own pinned source, including the negative result that a generic reranker made things worse — the kind of finding most vendors would just not publish.
Searching your code means sending it to someone else's cloud.
Local-first by default via fastembed on CPU, no API key required. .gitignore is respected during indexing. Cloud embedding providers are opt-in and see only the chunks being embedded, never the whole repo.
MCP Tools
Available via Model Context Protocol for AI assistants
semantic_search Natural language code search across your entire codebaseview_signatures Function/type signatures and structure without reading full implementationsgraphrag Always-on file/symbol graph — relationships, path finding, overview, no indexing requiredstructural_search AST pattern matching — find calls, instantiations, and syntax shapes, not textlsp_goto_definition Jump to a symbol's definition (requires --with-lsp)lsp_find_references Find every usage of a symbol across the workspace (requires --with-lsp)lsp_hover Type info and documentation for a symbol (requires --with-lsp)lsp_document_symbols / lsp_workspace_symbols / lsp_completion File and workspace symbol search, completions (requires --with-lsp)When to Use Octocode
Developer Onboarding
New to a codebase? Ask "how does the payment flow work?" and get a full cross-file trace in seconds — no hours of grepping and reading unfamiliar code first.
AI Pair Programming With Real Codebase Awareness
Claude or Cursor get semantic search, graph relationships, and — with --with-lsp — compiler-verified go-to-definition and find-references, not just the contents of whatever file happens to be open.
Refactoring & Blast-Radius Analysis
graphrag shows every caller and importer before you touch a function. structural_search finds every instance of a pattern across the tree regardless of naming or formatting.
Code Review by Intent
"Show me all error handling in the API layer" gets a structural answer spanning every file that matches — review by intent, not by clicking through a file tree.
Works With
Supported Languages
Install
Homebrew
brew install muvon/tap/octocode One command. Auto-updates. No build step.
Build from Source
git clone https://github.com/muvon/octocode && cd octocode && cargo build --releaseTech Stack
Built in the Open
Octocode is open source under the Apache 2.0 license. Contributions, issues, and stars are welcome.