Muvon/octocode

What it is

Octocode is a command-line tool (written in Rust) that helps you and your AI coding assistants explore a codebase. It's both a search engine for code and a relationship map that shows how files and symbols (functions, classes, etc.) connect to each other.

It speaks a protocol called MCP (Model Context Protocol), which is a standard way for AI assistants like Claude Code, Codex, Cursor, or Windsurf to plug into external tools. So you can run Octocode and let your AI assistant query your codebase through it — or you can search directly from your terminal.

The two ways it works

Octocode has two complementary mechanisms:

1. Live source parsing — Reads your current source code directly using a parser called Tree-sitter. This requires no index, no embeddings, and no AI models. It extracts symbols and relationships (imports, calls, inheritance, implementations) on the fly. Features that use this: structural search (find definitions and usages), viewing function signatures, and the live dependency graph.

2. Indexed semantic search — You first run octocode index to build a search index. It embeds your code as vectors (using a local model called FastEmbed) and also indexes keywords (using a technique called BM25). When you search, it combines both approaches and re-ranks results. This lets you find code "by intent" — e.g., typing "authentication middleware" surfaces relevant code even if it doesn't contain those exact words.

The README lays it out as:

Current source → Language parsers → Live file and symbol graph → MCP tools
Indexed code   → Embeddings + BM25 → Hybrid search + reranking → CLI / MCP

Key capabilities

Capability	What it does	Needs an index?
semantic_search	Find code, docs, and indexed history by meaning	Yes
structural_search	Find definitions, usages, and code patterns in current source	No
view_signatures	Read function signatures and imports without loading whole files	No
graphrag	Explore live relationships between files/symbols and dependency paths	No (live version)
lsp_* tools	Definitions, references, hover info, completion — requires a language server (e.g., rust-analyzer)	No, but needs LSP server

Installation and basic usage

Install via one of these:

# Linux/macOS/Unix-shell-on-Windows
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# macOS
brew install muvon/tap/octocode

# Or from source
cargo install octocode  # requires Rust 1.95+ and protoc

Then, inside a Git repo:

cd /path/to/your/project
octocode index
ocotcode search "authentication middleware"

Other useful options:

• octocode search "auth" "middleware" "session" — combine related queries
• octocode search "..." --language rust — filter by language
• octocode search "..." --mode docs — search documentation instead of code
• octocode index --no-git — for directories that aren't Git repositories
• octocode watch — keep the index updated as files change (run separately alongside the MCP server)
• octocode graphrag overview — after enabling indexed GraphRAG (an optional persisted layer with semantic file discovery and optional LLM-generated descriptions)

No API key is needed by default — the embedding and reranking models download locally on first use. Remote providers (embeddings, reranking, LLMs) are optional and configurable.

Connecting to AI assistants

For Claude Code: claude mcp add --transport stdio octocode -- octocode mcp --path /path/to/your/project

For Codex CLI: codex mcp add octocode -- octocode mcp --path /path/to/your/project

For Claude Desktop, Cursor, or Windsurf: add a JSON entry to the client's MCP config with command: "octocode", args: ["mcp", "--path", "/path/to/your/project"].

To enable LSP (language server) tools: octocode mcp --path /path/to/your/project --with-lsp rust-analyzer

By default, the MCP server does not re-index — you rerun octocode index after code changes, or run octocode watch in a separate process.

OctoFS integration

OctoFS is a companion tool that gives AI assistants file-reading and atomic-edit capabilities. Octocode pairs with it: structural_search returns source lines formatted as N:hh|content where N:hh is a line ID (a hash of the original line, including indentation). OctoFS view and batch_edit use the same IDs, so an agent can search, then edit, without re-reading lines to find edit targets. OctoFS validates IDs before applying edits and flags stale targets if content changed. The N:hh| prefix is metadata, not part of the code. OctoFS is optional — Octocode works standalone.

The README also mentions Octomind, a companion AI agent runtime, whose developer:general agent bundles Octocode and OctoFS capabilities.

Supported languages

Rust, Python, TypeScript/JavaScript (.ts, .tsx, .js, .jsx), Go, PHP, C/C++ (many extensions), Ruby, Elixir, Java, Swift, Svelte, Lua, CSS/SCSS/Sass, JSON, Bash, and Markdown.

Privacy and configuration highlights

• Local models by default — embeddings and reranking run locally after model downloads; no API key required.
• Local storage — indexes live in Octocode's per-project data directory outside your repository.
• File exclusions — honors .gitignore and .noindex; you can configure more exclusions.
• Client caveat — even with local models, the AI assistant using Octocode may receive source content returned by tools.
• Remote providers optional — if you enable them, they receive queries and source content needed for those features. API keys go in environment variables.

Performance benchmark

The README includes historical benchmark results (dated June 21, 2026, using Octocode 0.17.1 — not the current release). On 127 code-search queries, with reranking disabled:

Configuration	Hit@5	Hit@10	MRR	NDCG@10	Recall@10
Dense vector only	0.598	0.717	0.485	0.528	0.671
Hybrid 0.7/0.3 (vector/keyword)	0.598	0.717	0.485	0.528	0.671
Hybrid 0.3/0.7	0.732	0.835	0.572	0.620	0.807

The takeaway: weighting keyword search more heavily improved results in that historical test. The README explicitly cautions these numbers don't measure the current release.

Bottom line

Octocode is a developer tool that gives AI assistants a structured, searchable view of a codebase — combining semantic search, exact structural search, and a live symbol/dependency graph — while running locally by default and supporting a wide range of languages.

License and contribution

Apache License 2.0, maintained by Muvon. Contributions welcome via GitHub Issues, Discussions, or email (opensource@muvon.io).

---

All facts above are drawn directly from the project README.