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.