CodeGraph 使用教程

📖 项目简介

CodeGraph 是一个 51k Star 的开源「代码知识图谱」工具。它用 tree-sitter 提前把你的整个代码库解析成 符号关系 + 调用图 + 代码结构 的知识图谱，存进本地 SQLite 数据库。这样 Codex、Claude Code、Cursor 等 AI 编程工具在探索代码时，一次查询就能直接拿到答案，不用再满项目 grep、翻一堆文件。

官方实测：在 7 个真实开源项目上对比，平均 省 47% token、少 58% 工具调用、快 22%、便宜约 16%，而且 100% 本地运行，不联网、不要 API Key。最适合 Codex 这种按 token 计费、又爱满项目翻代码的场景。

💡

一句话理解：给 AI 编程工具装一个「提前建好索引的大脑」，它不再瞎翻代码，又快又省钱。

📎 相关链接与下载地址（点击展开）

GitHub 项目： github.com/colbymchenry/codegraph
官网文档： colbymchenry.github.io/codegraph
npm 包： @colbymchenry/codegraph
更多教程：关注公众号 / 抖音 / 视频号「IT小圈」

✨ 核心亮点

💰

省 token 省钱

平均省 47% token、少 58% 工具调用，最猛省一半的钱

🔒

100% 本地

不联网、不要 API Key，只用本地 SQLite，数据不出本机

🔌

支持 8 大工具

Codex、Claude Code、Cursor、Gemini、opencode 等一套配置全适配

♻️

自动同步

边写代码边自动重建索引，零配置，索引永远不过时

支持 TypeScript、Python、Go、Rust、Java、C#、Swift、Kotlin 等 20 多种语言，还能识别 17 种 Web 框架的路由。

🚀 如何使用

第一步：安装 CLI

无需 Node.js，一条命令装好（macOS / Linux 用 shell 安装脚本，Windows 用 PowerShell 安装脚本）。已有 Node 的也可以用 npm 全局安装。

                        npm
                        npm i -g @colbymchenry/codegraph
                    

装完后新开一个终端，让 codegraph 命令生效。

第二步：连接你的 AI 工具

运行安装器，它会自动检测并配置 Codex、Claude Code、Cursor、Gemini 等已安装的工具，把 CodeGraph 的 MCP 服务接进去。

                        shell
                        codegraph install
                    

配置完成后重启对应的 AI 工具，让 MCP 服务加载。

第三步：在项目里建索引

进入你的项目目录，初始化并建图（一条命令搞定）。之后会自动同步，不用再手动 sync。

                        shell
                        cd your-project
codegraph init
                    

之后你的 AI 工具检测到 .codegraph/ 目录就会自动用上 CodeGraph，Codex 从此查代码又快又省。

✅

常用命令：codegraph status 看索引状态、codegraph upgrade 升级、codegraph uninstall 一键卸载。

❓ 常见问题

Q: 它会把我的代码传到云端吗？

不会。CodeGraph 100% 本地运行，不联网、不要 API Key，索引只存在本机的 SQLite 数据库里。只收集匿名的功能使用统计，可用 codegraph telemetry off 关闭。

Q: 我代码改了，索引会不会过时？

不会。它用操作系统原生的文件监听，改完文件 2 秒内自动重建索引；切换会话时还会做一次差异校对，保证 AI 拿到的永远是最新代码。

Q: 支持哪些 AI 编程工具？

Claude Code、Cursor、Codex CLI、opencode、Hermes Agent、Gemini CLI、Antigravity IDE、Kiro，安装器会自动检测并配置。

Q: 提示 "CodeGraph not initialized" 怎么办？

先在项目目录里跑一次 codegraph init 建好索引即可。