codeix
codeix.dev ·AI代理的快速语义代码搜索——在任何代码库中查找符号、引用和调用者。
codeix # start MCP server, watch for changes
codeix build # parse source files, write .codeindex
codeix -r ~/project build # build from a specific directory为什么
AI编码代理花费了大部分代币预算 *发现* 在他们可以之前编码 *从事* 他们grep，读取文件，再次grep，回溯。在大型代码库中，代理可能会在定位正确的函数时燃烧数千个令牌，或者更糟糕的是，完全错过它并产生幻觉。
Codeix为代理提供了一个预构建的代码库映射。 一个结构化查询返回符号名称、文件、行范围、签名和父级——无需扫描，无需猜测。
现有工具出了什么问题
| 问题 | 今天发生了什么 |
|---|---|
| 无结构 | grep 查找文本匹配项，而不是符号。代理无法区分函数定义和提及它的注释 |
| 重新解析速度慢 | 基于Python的索引器在启动时重新解析所有内容。在大型代码库中，您需要等待。 |
| 不可共享 | 索引是本地缓存——每台机器都是短暂的。新的开发人员或CI运行人员从头开始。 |
| 无成分 | Monorepo有10个包？依赖有用的API？无法跨越边界进行查询。 |
| 散文是看不见的 | TODO、docstring、错误消息——可通过grep搜索，但不能 *选择性地*。您不能只搜索注释而不搜索匹配的代码。 |
codeix有什么不同之处
- 致力于git --该指数是
.codeindex您用代码提交的目录。克隆仓库，索引已经存在。无需重新索引。 - 可共享的 --图书馆作者可以发货
.codeindex在他们的npm/PyPI/crates.io包中。消费者可以即时浏览依赖关系。 - 可组合 --MCP服务器自动发现依赖性索引并挂载它们。在一个地方查询您的代码和依赖关系。
- 为法学硕士构建 --符号有种类、签名、父关系和行范围。代理在一次工具调用中得到它所需要的东西，而不是从原始文本中拼凑出来。
- 散文搜索 —
search --scope text专门针对注释、文档字符串和字符串文字。找到TODO，找到用户报告的错误消息，找到函数的docstring所说的内容——没有代码噪音。 - 快速 --构建以秒为单位，查询以毫秒为单位。Rust+树保姆+内存中的SQLite FTS5。
这 .codeindex 格式
一种用于结构化代码索引的开放、可移植格式。与代码一起提交的普通JSONL文件——git友好的差异，人类可读 grep 和 jq，没有二进制blob。
.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示例 — 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子模块。不需要配置。
语言
树型语法，在编译时进行特征门控：
| 语言 | 功能标志 | 默认 | 扩展 |
|---|---|---|---|
python lang-python | 是的 | .py .pyi .pyw | |
| 生锈 | lang-rust | 是的 | .rs |
| JavaScript | lang-javascript | 是的 | .js .mjs .cjs .jsx |
| TypeScript | lang-typescript | 是的 | .ts .mts .cts .tsx |
| 去吧 | lang-go | 是的 | .go |
Java lang-java | 是的 | .java | |
C lang-c | 是的 | .c .h | |
C lang-cpp | 是的 | .cpp .cc .cxx .hpp .hxx | |
| 红宝石 | lang-ruby | 是的 | .rb .rake .gemspec |
C lang-csharp | 是的 | .cs | |
| Markdown | lang-markdown | 是的 | .md .markdown |
Markdown支持
Markdown文件被解析为 标题 （均为ATX # 以及Setext下划线样式），它们被索引为 section 具有层次父子关系的符号——支持TOC提取和文档结构导航。
围栏代码块提取如下 code 文本条目，位于其包含部分的父级。
嵌入式脚本
HTML、Vue、Svelte和Astro文件经过预处理以提取嵌入式 `` 块，然后用JavaScript或TypeScript语法解析：
| 格式 | 扩展名 | 脚本检测 |
|---|---|---|
| HTML | .html .htm | ` 标签，可选 lang="ts"` |
| 查看 | .vue | ` 和 ，可选 lang="ts"` |
| 斯维尔特 | .svelte | `，可选 lang="ts"` |
星的 .astro | --- frontmatter（总是TypeScript）+可选 `` 标签 |
索引中的行号指向原始文件，而不是提取的脚本块。
安装
# 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 serveMCP客户端配置
添加到您的MCP客户端配置中（例如Claude Desktop、Cursor）：
{
"mcpServers": {
"codeix": {
"command": "codeix"
}
}
}设计原则
- 仅限本地 -没有网络，没有API密钥，可以脱机和气隙工作
- 确定性的 --同一来源总是产生相同的索引（干净的差异）
- 可组合 --依赖索引在查询时自动发现和挂载
- 极小曲面 --7个查询工具，零管理管道
建筑
看 docs/architecture.md 获取全套架构决策记录。
许可证
麻省理工学院或阿帕奇-2.0
