CodeGraph 简介：让 AI Agent 更懂你的代码结构

在使用 Codex CLI、Claude Code、Cursor 这类 coding agent时，一个常见问题是：Agent 需要先花大量时间去搜索文件、读取源码、推断调用关系，然后才能真正开始分析需求或修改代码。对于大型项目，这个过程很容易消耗大量 token 和工具调用。

CodeGraph 可以很好的解决这个问题。

它是一个本地优先的代码智能工具，可以把代码仓库解析成一个可查询的知识图谱。简单说，它会提前分析项目中的类、方法、函数、调用关系、导入关系、继承关系、文件结构等信息，并存储到本地数据库中。之后 AI Agent 不再需要通过全项目搜索来盲目定位代码，而是可以先利用 CodeGraph 提供的结构化索引快速确定相关符号、调用链和影响范围，再有针对性地读取关键源码文件。

Quick Start

CodeGraph 支持 macOS、Linux 和 Windows。

在 macOS / Linux 中可以直接执行：

ruby 复制代码

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

Windows PowerShell 中可以执行：

ruby 复制代码

irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex

如果已经安装 Node.js，也可以使用 npm：

bash 复制代码

npx @colbymchenry/codegraph

# 或全局安装
npm i -g @colbymchenry/codegraph

注册到 Coding Agent:

bash 复制代码

npx @colbymchenry/codegraph

自动识别本机已安装的 Claude Code、Cursor 等 Agent，并询问你要为哪些 Agent 写入 MCP Server 配置。

之后就可以进入你的项目目录重使用：

bash 复制代码

cd your-project
codegraph init -i

执行后，项目下会生成 .codegraph/ 目录。只要该目录存在，已配置好的 Agent 就可以自动使用 CodeGraph 提供的 MCP 工具。

其他常用cli命令：

codegraph index ：全量重建索引
codegraph sync：增量同步变更
codegraph status：查看索引状态

How It Works

CodeGraph 的工作流程可以分为四步。

scss 复制代码

files → Extraction (tree-sitter) → DB (nodes/edges/files)
            ↓
      Resolution (imports, name-matching, framework patterns)
            ↓
      Graph queries (callers, callees, impact)
            ↓
      Context building (markdown / JSON for AI consumption)

第一步是 Extraction，也就是代码提取。CodeGraph 使用 tree-sitter 解析源码，生成 AST，然后从 AST 中提取类、函数、方法、类型、调用、导入、继承等结构化信息。

第二步是 Storage，也就是本地存储。CodeGraph 会把提取出的节点、边和文件信息存入项目下的 SQLite 数据库：

bash 复制代码

.codegraph/codegraph.db

这意味着它不依赖外部服务，也不需要把代码上传到云端。

第三步是 Resolution，也就是关系解析。CodeGraph 会进一步解析函数调用指向哪个定义、import 指向哪个文件、类继承关系如何连接，以及一些框架相关的模式。

第四步是 Auto-sync，也就是自动同步。当 MCP Server 运行时，它会监听项目文件变化，并增量更新索引。这样你修改代码后，图谱也能保持更新。

整体流程可以理解为：

复制代码

源码文件
  ↓
tree-sitter 解析
  ↓
提取符号和关系
  ↓
写入 SQLite
  ↓
通过 MCP 暴露给 Agent
  ↓
Agent 查询调用链、影响范围、文件结构

CodeGraph MCP Server

CodeGraph 的MCP Server会向 Agent 暴露一些只读查询工具，例如：

复制代码

codegraph_search   查找符号
codegraph_callers  查找谁调用了某个函数
codegraph_callees  查找某个函数调用了谁
codegraph_impact   分析修改某个符号会影响哪些代码
codegraph_node     查看某个符号详情
codegraph_explore  一次性返回相关符号源码和关系图
codegraph_files    获取索引后的文件结构
codegraph_status   查看索引状态

对于 Agent 来说，这相当于多了一个"代码结构数据库"。当你问：

复制代码

某个功能是怎么实现的？

Agent 不必马上全项目搜索，而是可以先查入口、调用方、被调用方和影响范围，再去读取少量关键文件。

总结

CodeGraph 的本质是：把代码仓库提前解析成知识图谱，再通过 MCP 提供给 AI Agent 使用。

对于小项目，它的收益可能不明显；但对于多模块、大量业务类、调用链复杂的项目，它可以明显减少 Agent 的探索成本，让 Agent 更快定位功能入口、调用关系和修改影响范围。