codegraph 是面向 Claude Code、Cursor、Codex CLI 的 TypeScript 本地代码知识图谱与 MCP 服务器，用 tree-sitter 预索引代码符号、调用关系和框架路由，再把查询能力暴露给 AI 编程代理。它同时是 npm 包、CLI、库和 MCP server，项目数据保存在每个仓库的 .codegraph/ 目录。
来源：README + package.json + CLAUDE.md 查看 GitHub 仓库 →codegraph 解决的是 AI 编程代理在大仓库里反复 grep、glob、Read 消耗 token 和工具调用的问题：先把代码库做成本地知识图谱，再让代理直接查符号、调用链、上下文和影响范围。README 给出的基准来自 7 个真实开源仓库，报告平均成本、token、耗时和工具调用都有下降，但也说明小仓库收益会变窄。它的独特点不在于又做一个搜索工具，而是把 tree-sitter AST、SQLite FTS5、MCP 工具和多 Agent 安装器组合成可落地的本地工作流。对搜索“codegraph 是什么”“codegraph 怎么用”“codegraph 本地部署”的用户来说，项目价值集中在预索引、本地隐私和对 Claude Code/Cursor/Codex/opencode 的直接接入。
来源：README + package.json + GitHub ReleasesCodeGraph 用 tree-sitter 解析源代码 AST，抽取 functions、classes、methods 等节点，以及 calls、imports、extends、implements 等边。CLAUDE.md 说明抽取是确定性的，来自 AST 而不是 LLM 摘要，这让结果更适合做可重复的代码导航。README 的 How It Works 把这一层描述为 files 到 ExtractionOrchestrator 再到 SQLite Graph DB 的入口。
来源：README + CLAUDE.md索引结果进入项目内的 .codegraph/codegraph.db，并使用 SQLite FTS5 做全文搜索。README 明确写到 100% local、无 API key、无外部服务；CLAUDE.md 进一步说明 native backend 用 better-sqlite3，可透明降级到 node-sqlite3-wasm。这个选择把隐私、离线可用和符号检索放在同一个本地数据层里。
来源：README + CLAUDE.md + package.json作为 MCP server 运行时，它暴露 codegraph_search、codegraph_context、codegraph_callers、codegraph_callees、codegraph_impact、codegraph_node、codegraph_files 和 codegraph_status。README 把这些工具分别映射到符号搜索、任务上下文、调用者/被调者、影响半径、单节点详情、索引文件结构和索引健康检查。v0.8.0 release 还强化了 agent guidance，让代理直接使用 context/explore，而不是绕回文件读取式探索。
来源：README + GitHub ReleasesCodeGraph 会识别 Web 框架路由文件，生成 route 节点，并用 references 边连接到 handler、view、controller 或 resolver。README 列出 Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin、Axum、ASP.NET、Vapor、React Router、SvelteKit 等形态。v0.8.0 进一步新增 NestJS HTTP、GraphQL、microservice 和 WebSocket 场景的 route 节点。
来源：README + GitHub Releases + docs/2026-04-24-framework-resolver-extract.mdMCP server 会用 FSEvents、inotify、ReadDirectoryChangesW 等原生 OS 事件监听项目变更，并在 2 秒 quiet window 后做增量同步。README 说明它过滤到源文件并保持图谱新鲜，v0.8.0 release 还增加了 WSL2 /mnt 慢路径下跳过 watcher、改用 git hook 或手动 sync 的策略。这个设计让索引不是一次性快照，而是随代码编辑更新。
来源：README + GitHub Releases + CLAUDE.md交互式安装器会检测并配置 Claude Code、Cursor、Codex CLI 和 opencode，写入 MCP 配置和对应的 instructions 文件。CLAUDE.md 说明 installer targets 由 registry 管理，每个 target 自己处理配置路径、JSON/TOML/JSONC 写入和 instructions 路径。README 也提供了 non-interactive install 参数，适合脚本化安装。
来源：README + CLAUDE.md + package.jsonCLI 的 codegraph affected 会沿 import 依赖传递追踪，找出变更源文件可能影响到的测试文件。README 给出直接传文件、从 stdin 读取 git diff 文件列表、按 glob 过滤测试文件以及 CI hook 的示例。它把图谱能力从问答扩展到变更前的测试选择。
来源：READMECodeGraph 的主线数据流是 files -> ExtractionOrchestrator -> SQLite DB -> ReferenceResolver -> GraphQueryManager/GraphTraverser -> ContextBuilder -> CLI/MCP/API。src/index.ts 暴露 CodeGraph 类，统一 init/open/close、indexAll、sync、searchNodes、getCallers/getCallees、getImpactRadius、buildContext、watch/unwatch 等能力。src/extraction/ 负责 tree-sitter 包装、每种语言的 extractor、Svelte/Vue/Liquid/DFM 等非标准格式处理，并用 parse-worker 把重解析从主线程移开。src/db/ 封装 schema、prepared query 和 native/WASM SQLite adapter；src/search/ 提供 FTS5 查询解析与辅助评分；src/graph/ 处理 BFS/DFS、影响半径和高层图查询。src/resolution/ 承担 imports、path aliases、name matching 和 framework-specific patterns，框架 resolver 负责把 Web 路由补成 route 节点和 references 边。src/context/ 把搜索和图遍历的结果格式化为 Markdown/JSON 上下文，src/mcp/ 再把这些能力包装成 MCP tools，src/bin/codegraph.ts 则用 commander 暴露 install、init、index、sync、status、query、files、context、affected、serve --mcp 等命令。installer 另成一层，针对 Claude、Cursor、Codex、opencode 分别处理配置写入和 instructions 文件，并要求相关变更覆盖 installer-targets 测试。整体设计不是轻量脚本，而是明确分层的本地代码智能系统；这种分层有利于扩展语言和客户端，但 framework resolver、agent instructions、watcher/SQLite backend 的交叉点较多，维护上需要依赖测试和 release discipline 才能压住复杂度。
来源：README + CLAUDE.md + tree + docs/2026-04-24-framework-resolver-extract.md中心为项目本体，内环 = 核心功能模块，外环 = 关键技术依赖；按 deep.json 中的 core_features 与 tech_stack.key_deps 自动生成
tree-sitter-wasmsweb-tree-sitterbetter-sqlite3 optional native backendnode-sqlite3-wasm fallbackcommander@clack/promptsjsonc-parserpicomatch1. 大型仓库架构问答：先 codegraph init -i 建索引，再让 Claude Code/Cursor/Codex 通过 MCP 查询上下文，适合“codegraph 怎么用”类教程场景。 2. 变更前影响面评估：用 codegraph_callers、codegraph_callees、codegraph_impact 或 CLI 的 codegraph affected 判断函数、类和测试文件的影响范围。 3. Web 项目路由追踪：在 Django、FastAPI、Express、NestJS、Rails、Laravel、Spring、Gin 等项目里，把 URL pattern 追到 view/controller/handler。 4. 本地隐私敏感代码探索：需要“codegraph 本地部署”且不想把代码发到外部服务的团队，可把索引、SQLite 数据库和 MCP server 都放在本机。
来源：README + CLAUDE.md + GitHub Releases最新 GitHub Release 是 v0.8.0，发布日期 2026-05-20。主要变更包括新增 NestJS framework routes，codegraph_explore 输出 line numbers，WSL2 /mnt 慢文件系统下跳过 live watcher 并提供 git hook/manual sync 兜底；同时调整 MCP agent guidance、优化 codegraph_node includeCode、把最低 Node.js 提到 20，并修复 explore payload 超预算、untracked 文件反复 pending、嵌套独立 git repo 索引、Node 24 native SQLite backend、MCP project root 解析和 Claude Code 本地安装配置等问题。
来源：GitHub Releasescodegraph 开源项目的核心判断很清晰：它适合经常让 Claude Code、Cursor、Codex CLI 或 opencode 理解中大型代码库的开发者，而不是只偶尔搜几个文件的小仓库用户。想找“codegraph 是什么”的人，可以把它理解为本地预索引的代码知识图谱加 MCP server；想找“codegraph 教程”或“codegraph 怎么用”的人，README 的 npx installer 和 codegraph init -i 已经覆盖最短路径。务实建议是先在一个真实仓库跑 init、status、context/impact，再观察 agent 是否真的减少 grep/read 式探索。对强隐私、本地部署、跨语言仓库和框架路由追踪场景，它的技术取舍很贴合；如果你的项目很小、Node native SQLite backend 装不上、或团队不愿承担索引/同步/验证维护成本，短期内用原生搜索可能更省事。和普通代码搜索工具对比，codegraph 的优势在“可被 Agent 查询的图谱关系”，不是单纯全文检索。
来源：综合分析codegraph 是面向 Claude Code、Cursor、Codex CLI 的 TypeScript 本地代码知识图谱与 MCP 服务器，用 tree-sitter 预索引代码符号、调用关系和框架路由，再把查询能力暴露给 AI 编程代理。它同时是 npm 包、CLI、库和 MCP server，项目数据保存在每个仓库的 .codegraph/ 目录。
codegraph 的核心功能包括：tree-sitter 语义图谱索引、SQLite FTS5 本地图数据库、MCP 工具暴露图谱查询、框架路由节点与 handler references、原生文件事件增量同步。
codegraph 解决的是 AI 编程代理在大仓库里反复 grep、glob、Read 消耗 token 和工具调用的问题：先把代码库做成本地知识图谱，再让代理直接查符号、调用链、上下文和影响范围。README 给出的基准来自 7 个真实开源仓库，报告平均成本、token、耗时和工具调用都有下降，但也说明小仓库收益会变窄。
1. 大型仓库架构问答：先 codegraph init -i 建索引，再让 Claude Code/Cursor/Codex 通过 MCP 查询上下文，适合“codegraph 怎么用”类教程场景。 2. 变更前影响面评估：用 codegraph_callers、codegraph_callees、codegraph_impact 或 CLI 的 codegraph affected 判断函数、类和测试文件的影响范围。