codeix

🚀 codeix

Fast semantic code search for AI agents — find symbols, references, and callers across any codebase.

🚀 快速开始

以下是一些基本命令示例：

codeix                 # 启动MCP服务器，监听更改
codeix build           # 解析源文件，写入.codeindex
codeix -r ~/project build  # 从特定目录构建

✨ 主要特性

为何选择codeix

AI编码代理在处理代码之前，大部分的令牌预算都花在了查找代码上。它们会使用grep命令、读取文件、再次使用grep命令、回溯等操作。在大型代码库中，代理可能会消耗数千个令牌来定位正确的函数，甚至可能完全错过并产生错误结果。

Codeix为代理提供了一个预先构建的代码库地图。一次结构化查询就能返回符号名称、文件、行范围、签名和父级信息，无需扫描和猜测。

现有工具的问题

| 问题 | 当前情况 | |------|------| | 缺乏结构 | grep只能找到文本匹配项，而不是符号。代理无法区分函数定义和提及该函数的注释。 | | 重新解析速度慢 | 基于Python的索引器在启动时会重新解析所有内容。在大型代码库中，需要等待很长时间。 | | 不可共享 | 索引是本地缓存，是临时的，每台机器都不同。新的开发人员或CI运行器需要从头开始。 | | 无法组合 | 拥有10个包的单体仓库？包含有用API的依赖项？无法跨边界进行查询。 | | 文本不可见 | TODO、文档字符串、错误消息等可以通过grep搜索，但不能有选择地搜索。无法只搜索注释而不匹配代码。 |

codeix的不同之处

• 提交到git — 索引是一个.codeindex目录，你可以将其与代码一起提交。克隆仓库时，索引已经存在，无需重新索引。
• 可共享 — 库作者可以在他们的npm/PyPI/crates.io包中提供.codeindex。使用者可以立即导航依赖项。
• 可组合 — MCP服务器会自动发现依赖项索引并挂载它们。可以在一个地方查询你的代码和依赖项。
• 为大语言模型结构化 — 符号具有类型、签名、父级关系和行范围。代理在一次工具调用中就能获得所需的信息，而无需从原始文本中拼凑。
• 文本搜索 — search --scope text专门针对注释、文档字符串和字符串字面量进行搜索。可以找到TODO、用户报告的错误消息、函数文档字符串的内容，而不会受到代码的干扰。
• 快速 — 构建只需几秒钟，查询只需几毫秒。底层使用Rust + tree-sitter + 内存中的SQLite FTS5。

📦 安装指南

# npm / npx — 无需安装即可运行
npx codeix

# pip / uvx — 无需安装即可运行
uvx codeix

# Rust
cargo install codeix

# Homebrew
brew install codeix

# 或者从源代码构建
git clone https://github.com/montanetech/codeix.git
cd codeix
cargo build --release

所有渠道都安装相同的单个二进制文件，无需运行时依赖。

💻 使用示例

基础用法

# 为当前项目构建索引
codeix build

# 从特定目录构建（发现所有下方的git仓库）
codeix -r ~/projects build

# 启动MCP服务器（默认命令，监听更改）
codeix

# 或者显式指定
codeix serve
codeix serve --no-watch

# 从特定目录提供服务
codeix -r ~/projects serve

MCP客户端配置

添加到你的MCP客户端配置（例如Claude Desktop、Cursor）：

{
  "mcpServers": {
    "codeix": {
      "command": "codeix"
    }
  }
}

📚 详细文档

.codeindex 格式

一种用于结构化代码索引的开放、可移植格式。它是普通的JSONL文件，可以与代码一起提交，具有git友好的差异，使用grep和jq可以进行人类可读的查看，没有二进制文件。

.codeindex/
  index.json        # 清单：版本、名称、语言
  files.jsonl       # 每个源文件一行（路径、语言、哈希、行数）
  symbols.jsonl     # 每个符号一行（函数、类、导入，带有签名）
  texts.jsonl       # 每个注释、文档字符串、字符串字面量一行

任何可以解析JSON的工具都可以使用.codeindex。Codeix使用tree-sitter构建它，AI代理通过MCP（模型上下文协议）查询它。

示例 — symbols.jsonl：

{"file":"src/main.py","name":"os","kind":"import","line":[1,1]}
{"file":"src/main.py","name":"Config","kind":"class","line":[22,45]}
{"file":"src/main.py","name":"Config.__init__","kind":"method","line":[23,30],"parent":"Config","sig":"def __init__(self, path: str, debug: bool = False)"}
{"file":"src/main.py","name":"main","kind":"function","line":[48,60],"sig":"def main(args: list[str]) -> int"}

随包发布索引

在你的包中包含.codeindex，每个依赖于你的开发人员都可以立即导航你的API，无需设置，无需重新索引。适用于Git仓库、npm、PyPI和crates.io。

MCP工具

有七个工具，无需设置。代理可以立即进行查询，无需初始化、配置或刷新。 | 工具 | 功能 | |------|------| | explore | 探索项目结构：元数据、子项目、按目录分组的文件 | | search | 跨符号、文件和文本进行统一的全文搜索（FTS5，BM25排名），支持范围/类型/路径/项目过滤 | | get_file_symbols | 列出文件中的所有符号 | | get_children | 获取类/模块的子项 | | get_callers | 查找调用或引用符号的所有位置 | | get_callees | 查找函数/方法调用的所有符号 | | flush_index | 将待处理的索引更改刷新到磁盘 |

项目发现

从任何目录启动codeix。它会向下遍历，并将每个包含.git/的目录视为一个单独的项目，每个项目都有自己的.codeindex。适用于单仓库、单体仓库、兄弟仓库和git子模块，无需配置。

支持的语言

Tree-sitter语法，在编译时进行功能门控： | 语言 | 功能标志 | 默认 | 扩展名 | |------|------|------|------| | Python | lang-python | 是 | .py .pyi .pyw | | Rust | lang-rust | 是 | .rs | | JavaScript | lang-javascript | 是 | .js .mjs .cjs .jsx | | TypeScript | lang-typescript | 是 | .ts .mts .cts .tsx | | Go | lang-go | 是 | .go | | Java | lang-java | 是 | .java | | C | lang-c | 是 | .c .h | | C++ | lang-cpp | 是 | .cpp .cc .cxx .hpp .hxx | | Ruby | lang-ruby | 是 | .rb .rake .gemspec | | C# | lang-csharp | 是 | .cs | | Markdown | lang-markdown | 是 | .md .markdown |

Markdown支持

Markdown文件会解析标题（ATX #和Setext下划线样式），这些标题会被索引为具有层次父子关系的section符号，从而支持提取目录和导航文档结构。 围栏代码块会被提取为code文本条目，其父级为包含它们的部分。

嵌入式脚本

HTML、Vue、Svelte和Astro文件会进行预处理，以提取嵌入式<script>块，然后使用JavaScript或TypeScript语法进行解析： | 格式 | 扩展名 | 脚本检测 | |------|------|------| | HTML | .html .htm | <script>标签，可选lang="ts" | | Vue | .vue | <script>和<script setup>，可选lang="ts" | | Svelte | .svelte | <script>，可选lang="ts" | | Astro | .astro | ---前置元数据（始终为TypeScript） + 可选<script>标签 | 索引中的行号指向原始文件，而不是提取的脚本块。

🔧 技术细节

设计原则

• 仅本地使用 — 无需网络，无需API密钥，可离线和隔离使用。
• 确定性 — 相同的源始终产生相同的索引（干净的差异）。
• 可组合 — 依赖项索引在查询时会自动发现和挂载。
• 最小表面 — 7个查询工具，无需管理管道。

架构

请参阅docs/architecture.md以获取完整的架构决策记录。

📄 许可证

MIT OR Apache-2.0