Muvon/octocode

Structural code intelligence for AI agents — semantic search, knowledge graphs, and a built-in MCP server in one Rust binary. Give Claude, Cursor, and any MCP client a deep understanding of your codebase.

它是什么

Octocode 是一个用 Rust 编写的命令行工具，可帮助你和你的 AI 编码助手探索代码库。它既是代码的搜索引擎，也是显示文件和符号（函数、类等）如何相互连接的关系图。

它使用一种称为 MCP（模型上下文协议）的协议，这是 Claude Code、Codex、Cursor 或 Windsurf 等 AI 助手插入外部工具的标准方式。因此，你可以运行 Octocode，让 AI 助手通过它查询你的代码库——或者你也可以直接从终端搜索。

它的两种工作方式

Octocode 有两种互补机制：

实时源码解析 — 使用名为 Tree-sitter 的解析器直接读取当前源代码。这不需要索引、嵌入或 AI 模型。它会即时提取符号和关系（导入、调用、继承、实现）。使用此机制的功能：结构化搜索（查找定义和用法）、查看函数签名和实时依赖关系图。
索引语义搜索 — 首先运行 octocode index 构建搜索索引。它使用本地模型（称为 FastEmbed）将代码嵌入为向量，并将关键词建立索引（使用称为 BM25 的技术）。搜索时，它会结合两种方法并对结果重新排序。这使你可以“按意图”查找代码——例如，输入“authentication middleware”会显示相关代码，即使其中不包含这些确切单词。

README 将其描述为：

当前源码 → 语言解析器 → 实时文件和符号图 → MCP 工具
索引代码 → 嵌入 + BM25 → 混合搜索 + 重排序 → CLI / MCP

关键能力

能力	作用	需要索引？
`semantic_search`	按含义查找代码、文档和索引历史	是
`structural_search`	在当前源码中查找定义、用法和代码模式	否
`view_signatures`	无需加载整个文件即可读取函数签名和导入	否
`graphrag`	探索文件/符号之间的实时关系和依赖路径	否（实时版本）
`lsp_*` 工具	定义、引用、悬停信息、补全——需要语言服务器（例如 `rust-analyzer`）	否，但需要 LSP 服务器

安装和基本用法

通过以下方式之一安装：

# Linux/macOS/Unix 上的 Windows 外壳
curl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh

# macOS
brew install muvon/tap/octocode

# 或从源码安装
cargo install octocode  # 需要 Rust 1.95+ 和 protoc

然后，在 Git 仓库中：

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

其他有用的选项：

octocode search "auth" "middleware" "session" — 合并相关查询
octocode search "..." --language rust — 按语言筛选
octocode search "..." --mode docs — 搜索文档而不是代码
octocode index --no-git — 用于不是 Git 仓库的目录
octocode watch — 在文件更改时保持索引更新（与 MCP 服务器分开运行）
octocode graphrag overview — 启用索引 GraphRAG 后（一个可选的持久化层，具有语义文件发现和可选的 LLM 生成的描述）

默认情况下不需要 API 密钥——嵌入和重排序模型会在首次使用时本地下载。远程提供程序（嵌入、重排序、LLM）是可选的，可以配置。

连接 AI 助手

对于 Claude Code：claude mcp add --transport stdio octocode -- octocode mcp --path /path/to/your/project

对于 Codex CLI：codex mcp add octocode -- octocode mcp --path /path/to/your/project

对于 Claude Desktop、Cursor 或 Windsurf：在客户端的 MCP 配置中添加一个 JSON 条目，包含 command: "octocode"、args: ["mcp", "--path", "/path/to/your/project"]。

要启用 LSP（语言服务器）工具：octocode mcp --path /path/to/your/project --with-lsp rust-analyzer

默认情况下，MCP 服务器不会重新索引——你需要在代码更改后重新运行 octocode index，或者在单独进程中运行 octocode watch。

OctoFS 集成

OctoFS 是一个伴随工具，为 AI 助手提供文件读取和原子编辑能力。Octocode 与它配合使用：structural_search 返回格式为 N:hh|content 的源码行，其中 N:hh 是行 ID（原始行的哈希，包括缩进）。OctoFS 的 view 和 batch_edit 使用相同的 ID，因此代理可以搜索后编辑，而无需重新读取行来查找编辑目标。OctoFS 在应用编辑前验证 ID，如果内容已更改，则标记过期目标。N:hh| 前缀是元数据，不是代码的一部分。OctoFS 是可选的——Octocode 可以独立运行。

README 还提到了 Octomind，一个伴随 AI 代理运行时，其 developer:general 代理捆绑了 Octocode 和 OctoFS 功能。

支持的语言

Rust、Python、TypeScript/JavaScript（.ts、.tsx、.js、.jsx）、Go、PHP、C/C++（许多扩展名）、Ruby、Elixir、Java、Swift、Svelte、Lua、CSS/SCSS/Sass、JSON、Bash 和 Markdown。

隐私和配置要点

默认本地模型 — 嵌入和重排序在模型下载后在本地运行；无需 API 密钥。
本地存储 — 索引位于 Octocode 的每个项目的数据目录中，该目录在你的仓库之外。
文件排除 — 尊重 .gitignore 和 .noindex；你可以配置更多排除项。
客户端注意事项 — 即使使用本地模型，使用 Octocode 的 AI 助手也可能收到工具返回的源码内容。
远程提供程序可选 — 如果启用，它们会收到这些功能所需的查询和源码内容。API 密钥放在环境变量中。

性能基准

README 包含历史基准测试结果（日期为 2026 年 6 月 21 日，使用 Octocode 0.17.1 — 不是当前版本）。在 127 个代码搜索查询中，禁用重排序：

配置	Hit@5	Hit@10	MRR	NDCG@10	Recall@10
仅密集向量	0.598	0.717	0.485	0.528	0.671
混合 0.7/0.3（向量/关键词）	0.598	0.717	0.485	0.528	0.671
混合 0.3/0.7	0.732	0.835	0.572	0.620	0.807

要点：在历史测试中，更重地加权关键词搜索改善了结果。README 明确警告这些数字不能衡量当前版本。

结论

Octocode 是一款开发者工具，为 AI 助手提供结构化、可搜索的代码库视图——结合语义搜索、精确的结构化搜索和实时符号/依赖图——同时默认在本地运行并支持多种语言。

许可证和贡献

Apache License 2.0，由 Muvon 维护。欢迎通过 GitHub Issues、Discussions 或电子邮件（opensource@muvon.io）贡献。

以上所有事实均直接取自项目 README。