English · 简体中文
本地代码索引服务：用 MCP 把代码库结构交给 AI。
tree-sitter 解析 AST，把函数、调用图、模块依赖图、控制流图存进单个 SQLite 文件， 通过 32 个 MCP 工具供 AI 查询。让 AI 不必 grep、不必逐文件 Read， 就知道仓库里有什么、谁调用了谁、改一处会波及哪里。
- 本地优先 — 不调 LLM API、不上传源码、无遥测
- 结构化 — 调用边由 AST 解析得出，不是正则猜的
- 快 — 自扫描 38 文件 / 145 函数 / 7,570 调用边，3.4 秒
以 MCP server 接入 Claude Code、Cursor、VS Code、Windsurf、Codex 及任何支持 Model Context Protocol 的 client。代码搜索与代码导航（code navigation）走 SQLite FTS5， 语义簇走调用图 BFS，产物是一张可查询的代码图（code graph）。
agentic coding 的关键瓶颈不是模型能力，而是给它看什么：整仓塞进上下文会爆，靠 grep 又只能拿到碎片。Codindex 把仓库索引成一份可复用的 repo index，让 AI 按需取结构化 code context——而不是把几万行源码反复喂进去。
Codindex — a local-first code indexing, codebase indexing and code intelligence server for AI coding agents, doing static analysis and code analysis locally. Parses any repository with tree-sitter into a structural static-analysis index (function inventory, call graph and call chains, dependency graph, control-flow graph, impact analysis, dead-code detection) and serves it over MCP. Code search and navigation run on SQLite FTS5; semantic clusters come from call-graph BFS. 32 tools · 6 languages · MIT · no telemetry.
| 你想知道 | 用 grep 的做法 | Codindex |
|---|---|---|
谁调用了 scanProject？ |
正则匹配，跨文件/别名/方法调用全靠猜 | get_call_graph |
| 改这个函数波及哪些文件？ | 手工顺藤摸瓜，容易漏 | get_impact_analysis |
| 这个模块依赖了谁，有循环吗？ | import 正则，路径别名解析不了 | get_module_deps |
| 哪些函数从没被调用过？ | 基本做不到 | get_dead_code |
| 有没有可复用的现成实现？ | 靠记忆和全文搜索 | get_reuse_report |
| 这个函数的分支和循环长什么样？ | 读源码脑补 | get_cfg |
在 CodeGraph 仓库（146 个 TS 文件）上实测：AST 统计到 1,926 个函数， 让 Agent 用 grep 手工统计只得到约 951 个——差一倍，且 grep 拿不到调用关系。
需要 Node.js ≥ 22.5（依赖内置 node:sqlite）。
npm i -g codindex装好后：
codindex --version # 确认版本
codindex --mcp # MCP stdio 模式，交给编辑器挂载
codindex # Web UI → http://localhost:3100从源码安装（想改代码或跑测试时）：
git clone https://github.com/Bencibr/codindex.git codindex && cd codindex
npm install && npm run build
npm pack && npm i -g ./codindex-*.tgz仓库根 .npmrc 已声明 legacy-peer-deps=true（tree-sitter 语法包的 peer 范围互相冲突），
npm install 无需额外参数。开发用 npm run dev 起服务，npm test 跑测试（325 个用例）。
安装时若出现
npm warn allow-scripts tree-sitter-* (install: node-gyp-build)， 属正常提示：语法包自带预编译产物，跳过 install 脚本不影响使用。 想消除提示可执行npm approve-scripts --allow-scripts-pending。
任选其一：
# Web UI：打开 http://localhost:3100，填名称和路径，点「添加」→「扫描」# API
curl -X POST http://localhost:3100/api/projects \
-H "Content-Type: application/json" \
-d '{"name":"My Project","path":"/path/to/your/project"}'
curl -X POST http://localhost:3100/api/projects/{id}/scan// MCP
add_project { name: "My Project", path: "/path/to/your/project" }
scan_project { project_id: "xxx" }
装完不确定有没有生效，按下面四步走一遍（以扫描本仓库为例）：
1. 起服务
codindex # Web UI → http://localhost:31002. 注册项目 —— 返回体里的 id 就是后续所有接口要用的 project_id
curl -X POST http://localhost:3100/api/projects \
-H "Content-Type: application/json" \
-d '{"name":"Codindex","path":"/path/to/codindex"}'
# → {"id":"bace225b-...","name":"Codindex","status":"pending", ...}3. 扫描 —— 同步执行，返回即完成
curl -X POST http://localhost:3100/api/projects/bace225b-.../scan
# → {"status":"complete","files":38,"functions":145,"calls":7572,"types":31,"cycles":0}4. 验证能查
curl http://localhost:3100/api/projects/bace225b-.../overview
# → {"name":"Codindex","status":"ready","lastScanned":1794213971, ...}或者走 MCP：add_project → scan_project → get_project_summary，
最后一步会返回 {files: 38, functions: 145, types: 31, calls: 7568, modules: 9}。
看到 status: "ready" 且函数数不为 0，就说明整条链路通了。
Claude Code — 全局装好后直接用 codindex 命令（最省事）：
{
"mcpServers": {
"codindex": {
"command": "codindex",
"args": ["--mcp"],
"env": { "CODINDEX_DB": "/absolute/path/to/codindex.db" }
}
}
}或用命令：claude mcp add codindex -- codindex --mcp
不想全局安装，也可以直接跑克隆下来的源码（需要该 clone 已 npm install）：
{
"mcpServers": {
"codindex": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/codindex/src/index.ts", "--mcp"]
}
}
}Cursor / VS Code — 把同样的内容写进 .cursor/mcp.json 或 .vscode/mcp.json，
外层键改成 "servers"。
CODINDEX_DB必须是绝对路径，否则 MCP 子进程可能找不到数据库。
完整清单（参数、返回值、解析规则）见 docs/TOOLS.md。
| 类别 | 数量 | 代表工具 |
|---|---|---|
| 上下文与读取 | 6 | get_smart_context（三档深度）、get_context_bundle、get_function_context、get_function_body、get_function_list、get_file_content |
| 调用与影响 | 5 | get_call_graph、get_impact_analysis、get_bulk_impact、get_dead_code、get_raise_sites |
| 搜索 | 3 | search_code（FTS5 全文）、search_semantic（调用图 BFS 语义簇）、find_similar_functions |
| 结构 | 8 | get_project_summary、get_architecture_guide、get_module_deps、get_cfg、get_type_info、get_type_usage、get_export_inventory、get_bridge_map |
| 质量与追踪 | 5 | get_hotspots、get_reuse_report、get_test_coverage、get_change_guide、get_feature_tracking |
| 扫描 | 5 | add_project、scan_project、scan_project_incremental、start_watching、stop_watching |
| 合计 | 32 |
最常用的 get_smart_context 按 purpose 返回不同深度，避免为一点信息整段读源码：
| purpose | 返回 | 场景 |
|---|---|---|
explore |
摘要 + 文件 + 复杂度 + 调用者数 | 快速了解函数做什么 |
understand |
+ callers + callees + 类型 | 理解它在系统中的角色 |
modify |
+ 完整源码 + 影响文件 | 修改前的完整评估 |
除了工具，MCP 还提供 4 个 Resource（codindex://projects 及
codindex://projects/{id}/{overview,functions,features}）供客户端直接挂载，
以及 1 个 Prompt（codindex-guide）用于注入使用指引。见
docs/TOOLS.md。
扫描：优化后综合耗时 ~9s → ~3.5s（批量事务、批量 UPDATE、Map 索引替代嵌套循环）。 本仓库自扫描 3.4s，含进程启动。
AI 效率：我们跑了两轮，结论不一致，两个都放上来。
| 轮次 | 样本 | 工具调用 | 回传数据量 |
|---|---|---|---|
| 第一轮 | 单问题（架构概览） | 8 vs 17，−53% | 64KB vs 1.4MB，−95% |
| 第二轮 | 3 个问题 | 31 vs 28，+11% | — |
能可靠省下来的是单次回答的数据量：结构化查询返回几万字符，而不是几十万字符的源码。
这一点两轮都成立。
不能承诺的是调用次数一定下降——这取决于 Agent 是否真的信任并优先使用这些工具，
受提示词、模型版本影响。第一轮的 −53% 没能复现。完整记录在 src/tests/bench/。
它是向量检索 / RAG 吗？
不是。没有 embedding、没有向量库、不调模型 API。search_semantic 这个名字容易误解，
它实际是基于调用图做 BFS：找到种子函数后把调用邻居一并返回，结果可复现、可审计。
需要联网或上传代码吗？
不需要。数据落在单个 SQLite 文件（默认 data/codindex.db）。
和 LSP / IDE 跳转有什么不同？ LSP 面向编辑器里的即时导航；Codindex 面向「把整个仓库结构一次性交给 AI」—— 批量、可查询、可跨会话复用，还能算影响面、复用分和死代码。两者不冲突。
数据会过期吗？
start_watching 后文件变更 3 秒内同步。所有响应带 lastModified，可比对判断新鲜度。
| 症状 | 原因 | 处理 |
|---|---|---|
npm install 报 ERESOLVE could not resolve |
tree-sitter 各家语法包 peer 范围互斥（java ^0.21.1、python/rust ^0.22.1） |
仓库根 .npmrc 已写 legacy-peer-deps=true。若你删过或不在仓库根执行，加 npm install --legacy-peer-deps |
codindex 命令找不到 |
npm i -g 的 bin 目录不在 PATH |
npm config get prefix 看前缀，把 <prefix>/bin 加进 PATH |
| 启动报端口被占用 | 3100 已被别的服务（含 IDE 插件）占了 | PORT=3199 codindex |
| MCP 连上但查不到数据 / 库是空的 | CODINDEX_DB 用了相对路径，MCP 子进程 cwd 与你的 shell 不同 |
一律写绝对路径；或干脆不设，用默认 data/codindex.db |
| 函数数是 0、文件数却不为 0 | 语言不在支持列表内，或单文件 > 1MB | 见支持的语言 |
| 改了代码但结果没变 | 没重扫，或没开监听 | 调 scan_project_incremental，或 start_watching |
| 想从零重来 | 派生数据可随时重建 | 停掉进程，删掉 data/codindex.db*，重新扫描 |
.npmrc 那条最容易踩：它只在仓库根目录执行 npm install 时生效，
在子目录或别的目录装会重新触发 ERESOLVE。
| 语言 | 扩展名 | 提取内容 |
|---|---|---|
| TypeScript | .ts .tsx |
函数/方法/箭头函数、调用边、类型、import |
| JavaScript | .js .jsx .mjs .cjs |
同上 |
| Python | .py |
函数/方法、调用边、类字段 |
| Go | .go |
函数/方法（receiver）、调用边、struct 字段 |
| Rust | .rs |
函数/方法、调用边、struct/enum 字段 |
| Java | .java |
方法、调用边、类字段 |
单文件上限 1MB。未列出的语言不会被索引——宁可少支持，也不做「文件数统计上了、 函数却一个都解析不出来」的虚假覆盖。
Node.js ≥ 22.5 + TypeScript (ESM) · Tree-sitter · SQLite（内置 node:sqlite，
可选 better-sqlite3）+ Drizzle ORM + FTS5 · Hono · React 18 + MUI 5（CDN 直出，无前端构建）
· @modelcontextprotocol/sdk · chokidar · Vitest
| 文档 | 内容 |
|---|---|
| docs/ | 文档索引 —— 所有对外文档都收在这里 |
| docs/TOOLS.md | 32 个工具 + 4 个 Resource + 1 个 Prompt 的完整参考 |
| docs/API.md | Web API 路由、Web UI 页面、环境变量、PRD 功能追踪 |
| docs/CONTRIBUTING.md | 开发环境、提交流程、如何加语言 |
| docs/SECURITY.md | 漏洞报告渠道与安全边界 |
| CHANGELOG.md | 变更记录 |
| AGENTS.md / CLAUDE.md | 给 AI 助手的使用指南 |
开发常用命令：
npm run dev # tsx 直跑，改代码即生效
npx tsc --noEmit # 完整类型检查
npm test # 14 files / 325 tests（用临时库，不碰 data/）
npm run build # 产物在 dist/
codindex --help # CLI 用法MIT