Codeix

codeix

codeix.dev · 面向 AI Agent 的快速语义代码搜索——跨任意代码库查找符号、引用和调用者。

codeix                 # start MCP server, watch for changes
codeix build           # parse source files, write .codeindex
codeix -r ~/project build  # build from a specific directory

为什么

AI 编码 Agent 在开始处理代码前，大部分 Token 预算都花在了查找代码上。它们使用 grep、阅读文件、再次使用 grep、然后回溯。在大型代码库中，Agent 可能仅仅为了定位到正确的函数就耗费数千个 Token——更糟的是，可能完全错过它，转而产生幻觉。

**Codeix 为 Agent 提供预先构建的代码库地图。**一次结构化查询即可返回符号名称、文件、行范围、签名和父级——无需扫描，也无需猜测。

现有工具的问题

问题	目前的情况
没有结构信息	grep 查找的是文本匹配，而不是符号。Agent 无法区分函数定义和提及该函数的注释。
重新解析很慢	基于 Python 的索引器在启动时会重新解析所有内容。在大型代码库中，你只能等待。
无法共享	索引只是本地缓存——临时存在于单台机器上。新开发者或 CI 运行器都得从头开始。
无法组合查询	有 10 个包的 Monorepo？有实用 API 的依赖项？无法跨边界查询。
无法检索散文内容	TODO、文档字符串、错误消息——虽然可以用 grep 搜索，却无法有选择地检索。搜索注释时无法避免匹配代码。

codeix 的不同之处

• 随 Git 一起提交——索引是一个 .codeindex 目录，可与代码一起提交。克隆仓库后，索引已经就绪，无需重新索引。
• 可共享——库作者可以在 npm/PyPI/crates.io 包中包含 .codeindex。使用者可以立即浏览依赖项。
• 可组合——MCP 服务会自动发现依赖项的索引并挂载。可在同一处查询代码和依赖项。
• 专为大模型设计——符号包含类型、签名、父级关系和行范围。Agent 只需一次工具调用，就能获得所需内容，而不必从原始文本中拼凑信息。
• 散文内容搜索——search --scope text 专门搜索注释、文档字符串和字符串字面量。查找 TODO、用户报告的错误消息，或函数文档字符串中的内容——不会受到代码干扰。
• 速度快——几秒内完成构建，毫秒内完成查询。底层采用 Rust、tree-sitter 和内存中的 SQLite FTS5。

.codeindex 格式

一种开放、可移植的结构化代码索引格式。纯 JSONL 文件，可与代码一起提交——Git 差异友好，可用 grep 和 jq 阅读，不含二进制文件。

.codeindex/
  index.json        # manifest: version, name, languages
  files.jsonl       # one line per source file (path, lang, hash, line count)
  symbols.jsonl     # one line per symbol (functions, classes, imports, with signatures)
  texts.jsonl       # one line per comment, docstring, string literal

任何能够解析 JSON 的工具都可以使用 .codeindex。Codeix 使用 tree-sitter 构建索引，AI Agent 则通过 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 工具

七种工具，零配置。Agent 可立即进行查询——无需初始化、配置或刷新。

工具	功能
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	--- frontmatter（始终为 TypeScript）+ 可选 <script> 标签

索引中的行号指向原始文件，而非提取出的脚本块。

安装

# npm / npx — run without installing
npx codeix

# pip / uvx — run without installing
uvx codeix

# Rust
cargo install codeix

# Homebrew
brew install codeix

# Or build from source
git clone https://github.com/montanetech/codeix.git
cd codeix
cargo build --release

所有渠道安装的都是同一个独立二进制文件。无需运行时依赖。

用法

# Build the index for the current project
codeix build

# Build from a specific directory (discovers all git repos below)
codeix -r ~/projects build

# Start MCP server (default command, watches for changes)
codeix

# Or explicitly
codeix serve
codeix serve --no-watch

# Serve from a specific directory
codeix -r ~/projects serve

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop、Cursor）：

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

设计原则

• 仅限本地 — 不使用网络，无需 API 密钥，可离线及在隔离网络环境中运行
• 确定性 — 相同源码始终生成相同索引（差异清晰）
• 可组合 — 依赖项索引会自动发现，并在查询时挂载
• 精简接口 — 7 个查询工具，不含管理层面上的额外机制

架构

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

许可证

MIT OR Apache-2.0