codegraph 是一个本地代码知识图谱，以 8 个 MCP 工具的形式对外暴露。它通过 O(1) 的 SQLite 查询与 FTS5 搜索来加速代码探索，大幅减少在代码库中定位方向所需的 grep + Read 循环。
用途
codegraph 面向既有（brownfield）代码库，帮助开发者快速建立对代码结构的认知与遍历。它不替代 grep：codegraph 是基于 tree-sitter 的调用图近似，而非编译器级实现，速度快、token 消耗低，但不可靠（存在假阴性）。应将其视为定位与遍历的加速器，而把 grep 作为完整性的真相来源。
何时使用
- 结构不直观的既有仓库；
- 任务涉及“X 在哪里被使用”“改动 Y 会影响什么”“追踪从 A 到 B 的流程”；
- 长时间运行的会话——冷启动成本可在多次查询中摊薄。
何时不使用
- 单文件编辑或简单查找；
- 会话时长可能短于冷启动成本（参见 references/spike.md 中按仓库给出的数据）；
- 仓库未初始化、且没有缓存的 .codegraph/、且会话较短。
可靠性与限制（在信任结果前请先阅读）
codegraph 构建于 tree-sitter 而非编译器之上，因此其调用/引用边是近似值。它存在三种已确认的失败方式，由此得出总原则：
grep 是完整性的真相来源。codegraph 是定位与遍历的加速器。切勿颠倒二者。
这种不对称性是全部论据所在：对于重构而言，假阴性是危险的（漏掉一个调用方，就会发布一个破坏性变更）；假阳性只是令人烦扰（看一眼即可丢弃）。codegraph 有假阴性，grep 没有。因此 codegraph 可以提出建议并排序，但当答案必须穷尽时，必须用 grep 确认。
三种失败模式（在约 580 个文件的 Rust+TS 仓库上测得）：
-
不可靠的边 → 假阴性。当接收者类型无法仅从语法解析时（对局部变量、泛型、trait 对象的调用），callers/callees/impact 会漏掉真实调用点。实测：一个真实有 8 个调用方的方法只返回 2 个——被丢弃的 5 个是 local.method() 与泛型分发调用点，且没有任何警告。对唯一的自由函数 + 直接调用是精确的（已验证 1/1、2/2）；对方法分发不可靠。
-
名称解析模糊且不区分重载。裸名称查询采用前缀匹配（useWorkspace 会回答 useWorkspacesQuery——一个不同的符号），并混淆重载（execute 有 19 个定义，却返回了 sqlx 的 .execute() 数据库调用，而非 trait 方法）。对于任何有多个定义的名称，应改用 codegraph_node 指定具体符号 id；裸 callers/callees 无法归因。
-
索引滞后于磁盘。CLI 在 codegraph sync（约 0.3s）之前看不到任何内容；MCP 文件监视器将差距缩小到约 1–2s。编辑之后立即查询，索引是错的——在它追上之前，grep/Read 才是真相。
决策矩阵
- 定位 / “解释子系统 X” / 首次勘察：codegraph explore。一次调用、带排序、逐字源码——上下文远少于 grep+Read。
- 唯一命名自由函数的调用方：codegraph callers（可信）。对唯一名称 + 直接调用精确。
- 签名变更 / 重命名前查找所有调用方：grep 权威；codegraph 仅用于预排序。此处 codegraph 不可靠——完整性不能依赖它。
- 任何重载名称（execute、lookup、run、new）：grep，或对具体 id 使用 codegraph node。裸名称 codegraph 会不可预测地混淆 / 解析不足。
- 核心类型的影响：codegraph impact --depth 1 预排序，再用 grep 确认。默认 depth-2 会膨胀（测试函数 + 每个文件一个文件入口），且未按深度排序。
- 刚编辑过的代码：grep（或先 codegraph sync）。索引在重建前是过期的。
- trait 分发 / 泛型调用点：grep + 阅读。两者都弱；codegraph 会静默丢弃它们，grep 至少能呈现文本。
工作流：先用 explore 获取地图，用 callers/impact 获取方向——但一旦答案必须完整（重命名、“我是否覆盖了所有人？”），就用 grep 确认，并将任何 codegraph 与 grep 的差异视为“codegraph 漏掉了”，而非“grep 过度匹配”。
前置条件
- PATH 中有 Node 18+；
- 项目有 .codegraph/（若没有，运行 codegraph init）；
- 对于云会话：通过 references/spike.md 为目标仓库验证冷启动成本。
文件
- references/install.md —— 本地 / Claude Code Cloud / devcontainer 的安装说明；
- references/usage.md —— 何时使用 8 个 MCP 工具中的哪一个，含主会话与子代理规则；
- references/spike.md —— 冷启动测量协议；在云会话中依赖 codegraph 之前，对每个新目标仓库运行一次。
已知集成目标
冷启动在本地测得（Node 22，4 核）。云冷启动仍待定——在云会话中依赖这些数字前，请重新运行 references/spike.md。
- onsager-ai/onsager：578 个索引文件（rust + tsx/ts），8.6k 节点 / 20k 边，数据库 24 MB，冷启动 init+index 12s，查询墙钟约 0.9s。
- crawlab-team/crawlab：644 个索引文件（go），6.8k 节点 / 15k 边，数据库 11 MB，冷启动 init+index 6s，查询墙钟约 0.9s。
- codervisor/leanspec：695 个索引文件（tsx/rust/ts），8.9k 节点 / 21k 边，数据库 23 MB，冷启动 init+index 10s，查询墙钟约 0.9s。
每次查询的墙钟时间主要由 Node 启动主导——SQLite 本身的工作是毫秒级。对于此规模级别的仓库，包含一次性 npx 安装的端到端冷启动约为 13–19s。