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

现有工具的问题

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工具

有七个工具，无需设置。代理可以立即进行查询，无需初始化、配置或刷新。

项目发现

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

支持的语言

Tree-sitter语法，在编译时进行功能门控：

Markdown支持

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

嵌入式脚本

HTML、Vue、Svelte和Astro文件会进行预处理，以提取嵌入式<script>块，然后使用JavaScript或TypeScript语法进行解析：

🔧 技术细节

设计原则

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

架构

请参阅以获取完整的架构决策记录。

📄 许可证

MIT OR Apache-2.0