夜雨聆风用Claude Code、Cursor这类AI编程助手的同学，可能都有个感受：它们干活挺猛，但烧token也猛。
尤其遇到大项目，AI跟没头苍蝇似的到处翻文件——grep扫一遍，glob找一遍，找不到再读一遍。一圈下来，几十次工具调用打底，钱哗哗的。
CodeGraph就是来解决问题的。
给AI配一个代码知识图谱，它想问什么直接查，不用再满世界乱翻。实测结果：平均省35%的费用，减少70%的工具调用。
项目完全开源，MIT协议，100%本地运行，不上传任何代码。
装起来有多简单？
不用装Node.js，一条命令搞定：
macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | shWindows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex如果机器上已经有Node，也可以走npm：
npx @colbymchenry/codegraph # 零安装运行# 或者全局装npm i -g @colbymchenry/codegraph装完跑一下安装向导，它会自动检测你机器上的Claude Code、Cursor、Codex CLI、opencode、Hermes Agent，问你要给哪个配好MCP服务。一路选就行，配置文件自动写好。
然后进你的项目目录：
cd your-projectcodegraph init -i重启AI助手，完事。
到底能省多少？
作者拿7个真实开源项目测了一遍。每个项目跑4次，问同一个架构问题，对比有无CodeGraph的结果。
平均：35%更便宜，59%更少token，49%更快，70%更少工具调用。
注意看Gin那个小项目（150个文件），native搜索本来就够快，所以差距不大。但上了规模，优势立刻拉开——大项目里AI几乎不需要读文件，直接查索引就能回答。
它能干什么？
智能上下文构建给AI一个任务描述，一次调用返回相关的入口点、关联符号和代码片段。AI不用再派一堆探索子agent到处挖。
全文本搜索内置FTS5全文索引，整个代码库按名字搜符号，毫秒级。
影响分析改一个函数之前，先查清楚谁调用了它，它调用了谁，改了会影响多大范围。
实时同步文件监听走操作系统原生事件（FSEvents / inotify / ReadDirectoryChangesW），代码一保存，图谱自动更新。不用配。
支持19+种语言TypeScript、JavaScript、Python、Go、Rust、Java、C#、PHP、Ruby、C、C++、Swift、Kotlin、Dart、Lua、Luau、Svelte、Liquid、Pascal/Delphi
框架感知的路由能认出Django、Flask、FastAPI、Express、NestJS、Laravel、Rails、Spring、Gin等14种框架的路由定义，把URL模式和handler函数关联起来。查一个controller的调用者，能直接看到是哪个URL在绑它。
100%本地数据不出机器，不用API key，没有外部服务。底层就是个SQLite库。
完整命令参考
安装与配置
curl ... | sh | |
irm ... | iex | |
npx @colbymchenry/codegraph | |
npm i -g @colbymchenry/codegraph | |
codegraphcodegraph install | |
codegraph install --yes | |
codegraph install --target=cursor,claude --yes | |
codegraph install --location=local | |
codegraph install --print-config codex |
项目初始化与索引
codegraph init [path] | -i同时索引） |
codegraph uninit [path] | |
codegraph index [path] | --force强制重建） |
codegraph sync [path] | |
codegraph status [path] |
查询与分析
codegraph query <搜索词> | --kind、--limit、--json） |
codegraph files [path] | --format、--filter、--max-depth） |
codegraph context "任务描述" | --format、--max-nodes） |
codegraph affected <文件...> |
affected 常用用法
# 直接指定文件codegraph affected src/utils.ts src/api.ts# 从git diff获取文件列表git diff --name-only | codegraph affected --stdin# 只输出文件路径（适合脚本）codegraph affected src/auth.ts --quiet# 自定义测试文件匹配模式codegraph affected src/auth.ts --filter "e2e/*"# JSON格式输出codegraph affected src/auth.ts --jsonMCP服务（供AI调用）
codegraph serve --mcp |
库方式调用（Node.js）
import CodeGraph from'@colbymchenry/codegraph';const cg = await CodeGraph.init('/path/to/project');await cg.indexAll({ onProgress: (p) =>console.log(p) });const results = cg.searchNodes('UserService');const callers = cg.getCallers(results[0].node.id);const context = await cg.buildContext('fix login bug', { maxNodes: 20 });const impact = cg.getImpactRadius(results[0].node.id, 2);cg.watch(); // 开启自动同步cg.close();工作原理
树状语法树（tree-sitter）解析源码，抽取出函数、类、方法这些节点，以及调用、继承、导入这些边。存进本地的SQLite数据库，开FTS5全文索引。
MCP服务器跑起来后，监听文件变动。改了代码，等两秒安静下来就增量更新图谱。
AI通过MCP工具查询时，直接从数据库拿结果，不用再扫硬盘。
MCP工具列表（AI可用的接口）：
codegraph_search | |
codegraph_context | |
codegraph_callers | |
codegraph_callees | |
codegraph_impact | |
codegraph_node | |
codegraph_files | |
codegraph_status |
常见坑
"CodeGraph not initialized"忘了在项目目录跑codegraph init。
索引慢检查.gitignore，确保node_modules、dist这类目录被排除在外。
MCP连不上确认项目已经初始化过，检查MCP配置里的路径对不对，试试手动跑codegraph serve --mcp看报错。
missing symbols等几秒让自动同步完成，或者手动跑codegraph sync。确认文件语言在支持列表里，且没有被.gitignore挡掉。
数据库被锁（database is locked）新版已经内置node:sqlite并开启WAL模式，读写不互斥。如果还遇到：
旧版本请重装（0.9以上） 检查 codegraph status看Journal模式是不是wal，如果不是（比如在WSL2的/mnt下），把项目移到本地磁盘。
最后说两句
CodeGraph的作者之前搞过类似的项目，这次直接打包了Node运行时，不用你自己配环境。安装脚本自动检测系统，下载对应的二进制。本质上把知识图谱做成了AI助手的“外挂缓存”——查过的不用再查，该知道的提前知道。
项目地址：https://github.com/colbymchenry/codegraph
觉得有用可以点个Star。