CodeGraph：为 AI Agent 打造的“代码地图”

工具介绍CodeGraph【https://github.com/colbymchenry/codegraph】 是一个本地优先的代码智能工具它的核心目标是让 AI 编程助手如 Claude Code、Cursor能快速、精准地找到所需代码而不是在文件海洋里低效搜索。工作原理它通过tree-sitter解析代码的抽象语法树AST提前将函数、类、调用关系、导入关系等结构化信息抽取出来构建成一个知识图谱。核心能力AI Agent 可以直接向 CodeGraph 提问瞬间得到答案。callers/callees查询某个函数的调用者和被调用者。impact分析修改某个符号如函数、类的影响范围。context针对一个具体任务如“修复登录问题”生成相关的代码上下文。主要优势效率极高实测数据显示使用 CodeGraph 后AI Agent 的工具调用次数平均减少 71%Token 消耗降低 57%速度提升 46%。100% 本地运行无需网络没有 API Key 费用数据完全私有。即改即用支持自动同步代码变更后图谱会自动更新无需手动重建。Nodejs 安装安装命令npm i -g colbymchenry/codegraph // 或 npx colbymchenry/codegraph安装配置选择 AI 开发工具按需选择是否添加到 path选择是应用全部的项目还是当前项目按需选择是否允许CodeGraph 的命令自动运行是是否分享匿名使用数据当功能开启时CodeGraph 会收集与软件运行状况相关的技术信息不包括任何源代码、文件内容或个人身份信息。是否开启根据自己的隐私习惯是否允许在“如何/在哪里/追踪”这类提示词中默认的启动“前置代码图”的功能从而自动注入结构化的背景信息 选是安装完成基本使用项目初始化进入你的项目根目录执行以下命令构建知识图谱cd your-project codegraph initcodegraph init会创建.codegraph/目录并一次性完成整个代码库的索引。索引会自动遵循.gitignore规则node_modules等目录不会被纳入图谱。提示初始化完成后重启你的 AI 编程助手如 Claude Code、CursorMCP 服务器会自动加载。核心命令速查命令作用codegraph install运行交互式安装器连接 AI 助手codegraph uninstall从所有 AI 助手中移除 CodeGraphcodegraph init在项目中初始化并构建索引codegraph uninit从项目中移除 CodeGraphcodegraph index --force强制全量重建索引codegraph sync增量更新索引通常自动执行codegraph status查看当前索引的统计信息codegraph query 关键词按名称搜索符号codegraph context 任务描述为 AI 构建任务相关的代码上下文codegraph callers 符号名查找谁调用了某个函数codegraph callees 符号名查找某个函数调用了谁codegraph impact 符号名分析修改某个符号的影响范围codegraph affected查找受改动影响的测试文件codegraph serve --mcp手动启动 MCP 服务器与 AI 助手配合使用当你与 AI 编程助手Claude Code、Cursor 等对话时可以这样使用 CodeGraph 的能力第一步让 AI 加载 CodeGraph 指令“阅读 CodeGraph 的指令这样你就知道如何使用它”第二步验证连接“请验证 CodeGraph 是否已连接并且索引可用”之后AI 助手会自动调用 CodeGraph 提供的工具来回答你的问题。常用提问示例场景提问示例代码搜索“查找处理用户认证的代码在哪里”依赖分析“哪些代码依赖于UserService类”调用链追踪“追踪从 HTTP 请求到数据库的完整执行路径”架构概览“给我一个这个项目的架构概览”影响分析“如果我修改了认证模块会破坏哪些功能”上下文收集“收集我添加一个新的支付提供商所需的所有信息”注意事项对于全栈工程师一个项目都习惯于将前后端项目在同一个文件夹中打开my-project/ -- 这是你的大文件夹 ├── backend/ -- Spring Boot 项目根目录 └── frontend/ -- Vue 项目根目录如果直接在大文件夹根目录执行codegraph init不是一个好的做法索引混乱互相干扰CodeGraph 会把整个目录包括前后端代码视为一个巨大的项目来解析。这可能导致它错误地认为前端的某个函数调用了后端的某个同名函数产生大量“虚假的调用关系”污染索引数据让 AI 助手产生误判。管理不便牵一发动全身两个项目会共用一个索引目录.codegraph/和配置文件。当你只想重新索引后端时却需要连带前端一起处理增加了管理的复杂性。配置复杂难以精准排除为了不让索引混乱你需要通过复杂的ignore规则来手动排除对方项目的代码不仅繁琐而且容易出错。官方推荐的做法是在每个子项目的根目录下分别进行初始化。这样每个项目都有自己独立的、纯净的代码图谱。你可以按以下步骤操作分别为前后端项目建立索引假设你的大文件夹结构如下my-project/ -- 这是你的大文件夹 ├── backend/ -- Spring Boot 项目根目录 └── frontend/ -- Vue 项目根目录那么你需要分别进入这两个子目录执行初始化cd my-project/backend codegraph init cd ../frontend codegraph init初始化后当你通过 AI 助手如 Claude Code提问时它能够智能处理。如果你在问后端相关的问题如 “UserService的调用者是谁”AI 会自动查询backend项目的图谱。如果你明确提到了另一个项目如 “前端登录页调用了后端的哪个接口”AI 也能通过projectPath参数精确地跨项目查询。