codeindex

一款结构化代码智能引擎，以 MCP 服务 的形式为 AI 编码 Agent 提供支持。

它使用 tree-sitter（支持 40 多种语言）为代码库建立索引，构建 trigram 全文索引、倒排词索引和依赖关系图，然后通过 16 个 MCP 工具 对外提供服务。

 ┌─────────────┐   MCP (stdio)   ┌───────────┐            ┌──────────────────┐
 │  AI Agent   │ ◄─────────────► │ codeindex │  socket    │ codeindex daemon │
 │ (Claude,    │ 16 tools,       │  (relay)  │ ◄────────► │  one per         │
 │  Cursor…)   │ JSON-RPC        └───────────┘            │  workspace       │
 └─────────────┘                                          └────────┬─────────┘
 ┌─────────────┐   MCP (stdio)   ┌───────────┐                     │
 │  AI Agent   │ ◄─────────────► │ codeindex │ ◄───────────────────┘
 │  (session 2)│                 │  (relay)  │   tree-sitter parse (40+ langs)
 └─────────────┘                 └───────────┘   trigram + word index
                                                 dependency graph
                                                 one file watcher
                                                 snapshot persistence

每个针对仓库的会话都像以前一样通过纯 stdio MCP 通信。与此同时， 所有会话共享同一份索引：语法树只解析一次、只监视一次、只写入一次， 无论连接了多少个 Agent。过去，仓库上的 8 个会话意味着 8 份相同的索引、 8 个文件监视器和 8 个快照写入器；在一个包含 720 个文件的项目上测量， 每个会话的内存占用从 87 MB 降至 7 MB，而共享守护进程仅占用 77 MB。

原因

AI 编码 Agent 会耗费大量 token 阅读整个文件。codeindex 用几百个 token 就能回答结构性问题——符号大纲、定义、调用方、影响范围、依赖链——而不是成千上万个。

一次 plan_change 调用即可返回：符号的定义位置、所有调用点、文件的架构角色（上帝模块／稳定核心／孤岛／驱动程序）、需要检查的硬编码字面量，以及文件变更时完整的传递影响范围。

快速开始

如果你已安装 Node 18+，这是最简单的方式。无需安装其他内容，也不需要密钥或配置——这个 4 KB 的包只负责获取适用于你平台的二进制文件，并根据已发布的校验和进行验证：

claude mcp add codeindex -- npx -y @munhq/codeindex

没有 Node，或者你还想安装 skill 和 hook：

# Prebuilt binary + skill + MCP registration, in one command
curl -fsSL https://raw.githubusercontent.com/munhq/codeindex/main/install.sh | sh

# Or build from source:
cd zig && ./fetch-vendor.sh && zig build -Doptimize=ReleaseFast

Docker，适用于将 MCP 服务作为镜像安装的宿主环境。工作区以只读方式绑定挂载；codeindex 绝不会写入其中：

docker run -i --rm -v "$PWD:/workspace:ro" munhq/codeindex

注册到你的 AI Agent：

# Claude Code — the plugin is the one-step path. It ships the skill, both
# routing hooks and the MCP server together, and its launcher finds or fetches
# the binary.
claude plugin marketplace add munhq/codeindex
claude plugin install codeindex@codeindex

# Without the plugin (or for a different MCP client), register the binary
# directly. Do not do both: two registrations mean two servers, two copies of
# every tool schema, and two writers on one snapshot. install.sh detects the
# plugin and skips this step when it is present.
claude mcp add -s user codeindex -- ~/.local/bin/codeindex --mcp

# Cursor / Claude Desktop / other MCP clients: add to your config
{
  "mcpServers": {
    "codeindex": {
      "command": "npx",
      "args": ["-y", "@munhq/codeindex"]
    }
  }
}

所有列表都指向同一个服务：npm 上的 @munhq/codeindex、官方 MCP 注册表中的 io.github.munhq/codeindex，以及 Smithery 上的 munhq/codeindex。

下次 Agent 启动时，codeindex 会在后台为你的项目建立索引，并提供结构化查询服务。

MCP 工具

工具	功能
status	索引统计信息：文件数、符号数、索引状态、节省的令牌百分比、已索引的 workspace，以及 watcher 是否正在运行
search	在所有已索引文件中进行全文搜索，并由 Trigram 加速
find_symbol	按名称查找符号定义（函数、结构体、类等）
find_word	在倒排词索引中精确查找单词/标识符
find_callers	符号的调用位置及包含它的函数。按名称匹配，因此也会包含其他位置的同名定义
get_outline	文件的结构大纲（符号、行数）
get_tree	包含文件元数据的目录树
get_imports	查看指定文件导入或依赖了哪些文件
get_imported_by	反向依赖——哪些文件导入了此文件
get_change_impact	传递性影响范围：文件变更会导致哪些内容出错
plan_change	符号或文件的完整重构计划——定义、调用方、文件作用、字面值、影响范围
get_hot_files	按最近变更时间排序的文件
read_file	读取文件内容，可选指定行范围
read_symbol	仅读取符号的源代码（可选指定上下文行数）
index_workspace	为工作区目录建立索引或重新建立索引
analyze	运行 22 种代码分析之一（见下文）

分析（analyze 工具）

分析	检查内容
security	硬编码密钥、SQL 注入模式、不安全代码块、eval 的使用
dead_code	除自身定义外没有任何名称引用的符号，并与库包中未使用的公共 API 区分开
unwrap_audit	.unwrap() / expect / panic! 位置（Rust），并根据请求处理程序、循环或 main 是否能到达这些位置进行排序
test_coverage	没有测试覆盖的文件
architecture	架构异味——上帝模块、循环依赖、孤岛
crossref	跨文件符号引用
type_drift	跨模块的类型签名不匹配
db_schema	迁移创建但没有代码引用的表，以及没有迁移创建的 SQL ORM 模型
migration_parity	架构变更缺少对应迁移
manifest_compliance	package.json / Cargo.toml / go.mod 合规性问题
literal_scan	硬编码 URL、IP、端口、绝对路径、TODO
coupling	模块耦合度指标
cycles	循环依赖检测
duplication	重复实现的自由函数——同一任务被编写了两遍
clones	复制粘贴的函数体，不考虑名称和空白字符
spawn_scan	跨文件检查在循环或计时器中启动的解释器，并按启动开销乘以启动频率排序
deps	依赖项清单——重复版本、未引用的 crate、仅使用一次的 crate
leak_shapes	泄漏的形态，以及每种形态对应的判定运行时序列
logic_shapes	固定字节常量与部署该常量的单元的内存限制之间的关系，以及副本数 × 连接池大小与连接池管理器连接容量之间的关系
call_cost	按每个元素造成的数据库和 HTTP 往返次数对行循环进行排序，并沿调用图统计
field_contention	同一个声明状态字段由两个或更多所有者写入
health	汇总上述分析，生成一份索引健康报告

支持的语言

通过 tree-sitter 支持 40 多种语言：Rust、Python、TypeScript/TSX、Go、Zig、C、C++、Java、Ruby、Bash、C#、Kotlin、Lua、Scala、Elixir、R、Swift、Dart、Haskell、TOML、JSON、YAML、HTML、CSS、SCSS、SQL、HCL、Dockerfile、Markdown、Nix、Make 等。

配置

codeindex --mcp                          # Run as MCP server (stdio)
codeindex --mcp --no-daemon              # ...without sharing the workspace daemon
codeindex --daemon-idle-secs 0           # Keep the daemon resident indefinitely
codeindex --workspace ./my-project       # Index a specific directory
codeindex --project-id my-project        # Project identifier
codeindex -v                             # Print version
codeindex -h                             # Print help

# Environment variables
CODEINDEX_WORKSPACE=/path/to/project     # Same as --workspace
CODEINDEX_PROJECT_ID=my-project          # Same as --project-id

让它真正派上用场

如果服务注册后没有告诉 Agent 什么时候该调用它，它就会闲置；无论调用多便宜，闲置的索引都毫无用处。为此，插件按生效顺序提供了三项功能：

1. SessionStart 简报。 每个会话一次，约 240 个 token；在包含源文件的代码库中，它会说明 codeindex 已启用，以及针对每类代码问题该使用哪个工具。它会在 Agent 选择工具之前出现，而这正是唯一能影响首次选择的时机。
2. PreToolUse 提示。 在会话中的第 1、8 和 25 个代码问题时触发；当扫描即将回答一个索引能更好回答的问题时，它会指出该问题对应的工具。它不仅匹配 Read/Grep/Glob，也匹配 Bash，因为在通过 shell 处理文件工作的权限模式下，大多数扫描实际上都是这样发生的。
3. 技能，模型在判断任务需要时会加载它。

建议不敌习惯，因此，对于索引明显更胜一筹的狭窄场景，插件会直接拒绝，而不是试图说服：在此前已建立索引的项目中，命令行内容只有一个标识符搜索。它绝不会拒绝读取文件——执行 Edit 前必须先获取文件内容；也绝不会拒绝同时执行构建或测试的命令；而且会话中拒绝三次后便不再拒绝，因此它永远不会成为会话无法继续的原因。

此功能默认开启，关闭它只需一个开关，无需手动编辑文件。它是一个插件选项，因此 /plugin 会将其显示为“拒绝索引能更好回答的扫描”，Claude Code 会将你的选择传递给钩子。在插件之外，或针对单个会话，可通过环境变量中的 CODEINDEX_ENFORCE=0 覆盖此选项，并通过 CODEINDEX_ENFORCE=1 恢复启用。

与其凭空假设效果，不如实际测量：python3 plugin/measure_routing.py 会统计每个会话中有多少代码问题交给了扫描，有多少交给了索引，并覆盖此机器上的所有 Claude Code 主目录。

要索引哪个目录树

在 --mcp 模式下，工作目录属于客户端，而不是你；它通常也不是你的项目：Claude Code 会从插件自身目录启动插件的 MCP 服务，从配置目录启动用户范围的服务。因此，工作区会按以下顺序确定，并采用第一个可用的结果：

1. --workspace 或 CODEINDEX_WORKSPACE。显式指定的路径绝不会被覆盖。
2. CLAUDE_PROJECT_DIR，Claude Code 会在它启动的每个 MCP 服务中设置此变量。
3. 启动目录；向上查找 .git、package.json、Cargo.toml、go.mod、build.zig 或 pyproject.toml 标记。
4. 客户端的 MCP roots。只要上一步得到的是推测结果，服务就会在握手时请求这些目录；如果该推测被拒绝，或路径不在客户端报告的任何目录中，就会采用其中一个。notifications/roots/list_changed 也会得到处理，因此通过 --add-dir 添加的目录仍可挽救当前会话。

status 会将生效的根目录报告为 workspace，并将文件监视器是否正在运行报告为 watcher。如果结果为空，请检查这两项：索引了错误的目录树，也会像索引了正确的目录树一样，对每个问题给出同样自信的回答。

它会拒绝索引整个主目录、文件系统根目录，或仅包含多个独立代码库的文件夹。对于被拒绝的工作区，每次查询都会返回拒绝原因和唯一可修复问题的调用方式——使用项目路径调用 index_workspace——而不是返回“没有结果”。

架构

• 解析器：使用 tree-sitter，支持 40 多种语法，编译为单个二进制文件
• 索引：使用三元组索引进行模糊文本搜索，使用倒排词索引精确查找标识符
• 依赖图：解析文件级导入关系，包含正向和反向边
• 版本存储：使用序列号跟踪文件变更，以支持增量更新
• 实时监视器：在文件创建、修改或删除时重新建立索引（MCP 模式下使用后台线程）。Linux 上使用 inotify；macOS 和 Windows 上使用轮询遍历，每隔几秒比较一次修改时间和文件大小。status 会通过 watcher_backend 报告当前使用的后端。
• 快照：将完整索引持久化到 .codeindex.json，这样重启时会加载快照，而非重新建立索引
• MCP 服务：通过 stdio 使用 JSON-RPC，实现 MCP 2024-11-05 协议
• 工作区守护进程：仓库中的第一个会话会启动后台守护进程，并作为中继连接到它；之后的会话只需连接即可。在 Linux、macOS 和 Windows 10 1803+ 上使用 Unix 域套接字，套接字位于 $XDG_RUNTIME_DIR/codeindex（或 TMPDIR 下的用户专属目录），名称由工作区哈希和二进制文件版本共同确定，因此重新构建的二进制文件不会沿用先前版本的守护进程。如果 15 分钟内没有会话连接，它就会退出。遇到任何问题时，都会回退到进程内建立索引，这也是守护进程出现之前的运行方式。使用 --no-daemon 可将其关闭。

平台支持

除注明的情况外，CI 都会构建下表中的每个版本，并在对应平台上运行测试。status 会报告当前使用的实时监视器后端，因此无需猜测。

	二进制文件	在 CI 中运行测试	监视器	install.sh	插件
Linux x86_64	是	是	inotify	是	是
Linux aarch64	是	交叉编译	inotify	是	是
macOS aarch64	是	是	轮询	是	是
macOS x86_64	是	交叉编译	轮询	是	是
Windows x86_64	是	是	轮询	需要 shell	见下文
Windows aarch64	是	交叉编译	轮询	需要 shell	见下文

在 Windows 上，install.sh 和插件的启动器都是 shell 脚本，因此需要 Git Bash、MSYS2 或 Cygwin——它们会自动检测环境并解析对应的 .exe 资源。插件通过该启动器注册服务，因此没有 shell 的原生 Windows Claude Code 应直接注册二进制文件：

claude mcp add -s user codeindex -- C:\path\to\codeindex.exe --mcp

这里的任何文件都没有签名或公证。在 macOS 上，通过 curl 获取的二进制文件运行时不会触发 Gatekeeper 提示；通过浏览器下载的文件会被隔离，运行 xattr -d com.apple.quarantine codeindex 可清除隔离属性。

从源代码构建

需要 Zig 0.16.0。

cd zig
./fetch-vendor.sh    # Clone tree-sitter + 40 grammar repos
zig build -Doptimize=ReleaseFast
# Binary: zig/zig-out/bin/codeindex

运行测试：

cd zig && zig build test-bin && ./zig-out/bin/test

zig build test 会通过构建运行器的 IPC 协议将结果输出到 stdout，而链接的 tree-sitter C 源代码会通过其调试 printf 路径破坏该协议。构建测试二进制文件并直接运行，执行的是同一组测试，且不会受到该协议的干扰。

对比

	codeindex	ast-grep	ctags	LSIF	Sourcegraph
原生支持 MCP	是	否	否	否	否
节省令牌	是（提供大纲，不提供完整文件）	否	部分支持	是	是
单个二进制文件	是	是	是	否	否（服务端）
实时监视器	是（inotify / 轮询）	否	否	否	否
依赖图	是	否	否	是	是
影响范围	是（传递性）	否	否	否	部分支持
重构规划器	是（plan_change）	否	否	否	否
语言	40 多种	20 多种	50 多种	不定	不定

与 chat-recall 配合使用

codeindex 回答关于你眼前代码的问题。chat-recall 回答关于你已完成工作的疑问——它会为你的 Claude Code、Gemini CLI、Codex、OpenCode、Antigravity 和 Cursor 会话建立索引，汇总成一个可搜索的历史记录，并通过 MCP 暴露这些内容。

两者结合，弥补了 Agent 会遗忘的两方面：codeindex 避免它重新阅读本可以先概述的文件，chat-recall 则避免它重复已完成的工作。chat-recall 会检测 PATH 中是否存在 codeindex 二进制文件，若找到，就会注册四个额外的代码智能工具——两者互不依赖。

许可证

MIT。请参阅 LICENSE。