CodeGraph 是一个为 AI 编程助手（如 Claude Code、Cursor）“预建”的本地代码知识图谱工具。

"CodeGraph 是一个本地优先的代码知识图谱工具。它用 tree-sitter 解析代码，用 SQLite 构建索引，通过 MCP 协议让 AI Agent 理解你的整个代码库——而不是一次只读一个文件。"

它的核心思想是：在AI开始工作前，就把你的整个代码库解析成一张结构清晰的“代码地图”。这样一来，AI 在回答问题时，可以直接“查阅”这张地图来获取精准信息，而无需像以前一样，在庞大的代码文件夹中反复搜索和阅读文件。

🤔 它解决了什么问题？

AI 编程助手在处理大型或陌生代码库时，通常采用“探索式”方法，通过反复执行 grep、glob、Read 等操作来寻找代码。这个过程不仅消耗大量 Token，导致成本高昂、响应变慢，而且AI获取的信息零散，难以形成对代码结构的整体理解。

CodeGraph 通过“预索引（Pre-indexed）”的方式，将这种昂贵的运行时探索，转变为一次性的、可持续更新的本地索引。

⚙️ 它的核心机制是什么？

CodeGraph 的工作流程可以概括为三个步骤：

1. 解析与抽取：它使用 tree-sitter 解析器，像编译器一样分析你的代码，抽取出代码中的“节点（Nodes）”和“边（Edges）”。

   • 节点：代表代码中的核心单元，如函数、类、方法、组件、路由等。

   • 边：代表这些单元之间的调用、导入、继承、引用等关系。

2. 存储与索引：将所有抽取出的节点和边，存入一个本地的 SQLite 数据库中。同时，它会建立全文搜索（FTS5） 索引，方便快速检索。

3. 提供服务：通过 MCP（模型上下文协议）服务器，将图谱的查询能力暴露给 AI 编程助手。AI 可以直接调用这些工具来查询图谱。

为了让“代码地图”始终保持最新，CodeGraph 还内置了文件监听器，能在你保存代码后自动进行增量更新，无需手动干预。

🚀 实际效果如何？

根据官方在多个真实开源项目（包括 VS Code、Django 等）上的基准测试，使用 CodeGraph 能带来显著的效率提升：

• Token 消耗减少：平均减少 57%，在大项目（如 VS Code）上甚至可减少 64% 至 70%。

• 工具调用减少：平均减少 71%，大项目上可减少 81% 至 89%。

• 成本与时间降低：平均成本降低 35%，任务执行时间减少 46%。

💡 如何开始使用？

安装和使用 CodeGraph 非常直接，主要分为三步：

1. 安装：在你的终端中运行安装命令。

# 使用安装脚本 (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# 或使用 npm
npm install -g @colbymchenry/codegraph

1. 配置：运行 codegraph install，它会自动检测你电脑上的 AI 编程工具（如 Claude Code, Cursor），并完成 MCP 服务器的连接配置。

2. 初始化：进入你的项目目录，运行 codegraph init。CodeGraph 会开始解析整个项目，并在项目根目录下创建一个 .codegraph/ 文件夹来存放知识图谱数据。

完成这三步后，当你再使用配置好的 AI 编程助手时，它就能自动利用 CodeGraph 提供的“代码地图”来理解和处理你的代码了。

🔧 常用命令速查

初始化后，你也可以通过命令行直接与 CodeGraph 交互：

总的来说，CodeGraph 更像一个为 AI 编程助手准备的本地“代码百科”，让 AI 从盲目搜索的“探索者”升级为按图索骥的“导航员”。