CodeGraph — AI 编程代理的代码知识图谱

CodeGraph — AI 编程代理的代码知识图谱

CodeGraph 是一个预索引的代码知识图谱工具，专为 AI 编程代理设计。它用一次工具调用替代传统代理大量的文件扫描和探索操作，让 AI 代理以「语义级」理解代码库。

官网地址：https://github.com/colbymchenry/codegraph

📊 核心数据

指标 数值
⭐ Stars 47.6k
🍴 Forks 2.9k
📜 许可证 MIT
📦 当前版本 v0.9.9（2026.6.2）
🌐 语言 TypeScript 92.6%
🏠 特点 100% 本地运行，零数据外泄

🎯 它能做什么

一句话：让 AI 编程代理不再逐文件”盲扫”代码库。

传统模式下，Claude Code 等代理需要花费大量工具调用去 find、grep、ls、逐个读文件来理解代码结构。CodeGraph 把这件事前置化——提前用 tree-sitter 解析源码 AST，建立符号级的关系图谱（谁调用谁、影响范围、路由映射），存入 SQLite 数据库。代理只需调一次 codegraph_explore 就能拿到完整上下文。

🚀 性能实测（Claude Opus 4.8 基准）

在 7 个真实开源项目上的表现：

平均：~16% 更便宜 · ~58% 更少工具调用 · ~47% 更少 Token · ~22% 更快

最亮眼的是 VS Code 代码库（~10k 文件）：工具调用减少 **81%**，Token 消耗减少 **64%**。

🔧 关键功能

  • 语义搜索：按符号名、函数、类直接定位，支持 FTS5 全文搜索
  • 调用链分析：追踪调用者（callers）、被调用者（callees）、影响半径（impact）
  • 自动同步：基于 OS 原生文件事件（inotify/FSEvents/ReadDirectoryChangesW），防抖自动增量更新
  • 20+ 语言支持：TS/JS、Python、Go、Rust、Java、C#、PHP、Ruby、Swift、Kotlin、Dart 等，跨文件覆盖率 84%~100%
  • 框架感知路由：识别 17 种 Web 框架（Django、Flask、Express、Rails、Spring、Gin 等）的路由，将 URL 模式链接到处理器
  • 跨语言桥接：iOS/React Native/Expo 的 Swift↔ObjC↔JS 流程追踪
  • 8 种代理自动适配：Claude Code、Cursor、Codex CLI、opencode、Hermes、Gemini CLI、Antigravity、Kiro

💻 快速上手

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 安装 CLI（自带 Node 运行时，无需预装）
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

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

# npm（适用于任何版本）
npm i -g @colbymchenry/codegraph

# 连接 AI 代理
codegraph install

# 初始化项目
cd your-project
codegraph init -i

之后当你在 Claude Code 等代理中工作时，它会自动通过 MCP 协议使用 CodeGraph 的索引来回答问题，无需手动触发。

💡 为什么值得关注

这个项目的核心洞察是：AI 代理在代码探索上浪费了太多预算。与其让模型花 80% 的 Token 在 grep + read 的机械操作上，不如预先建好一张”代码地图”。47.6k star 也说明这击中了开发者的真实痛点。

对我们当前 WorkBuddy 环境来说，如果你觉得在 MDPicSync 或 SpaceSnapper 等项目中代理探索代码库的效率不够高，CodeGraph 是个很值得一试的补充工具——完全本地、MIT 协议、安装一条命令。