colbymchenry/codegraph

项目概述

CodeGraph 是一个为 AI 编程代理（如 Claude Code、Cursor、Codex、Gemini 等）提供预索引代码知识图谱的工具。它通过 Rust 内核解析代码，构建包含符号、调用边和依赖关系的知识图谱，并自动同步代码变更，使代理能够通过一次工具调用获取精确的代码上下文，从而减少 token 消耗和工具调用次数，且完全在本地运行。

核心功能

• 预索引代码知识图谱：解析代码结构，构建符号、调用边和依赖关系图。
• 自动同步：通过文件监听器自动更新索引，无需手动重新运行。
• 精准上下文：一次工具调用返回相关符号、调用路径和影响范围。
• 多语言支持：支持 TypeScript、Python、Go、Rust、Java 等 20+ 种语言。
• 框架感知路由：识别 Django、Flask、Express 等 17 种 Web 框架的路由。
• 跨语言桥接：支持 Swift ↔ Objective-C、React Native 等混合代码库。
• 100% 本地：所有数据存储在本地 SQLite 数据库中，无外部服务。

适用与不适用场景

适用场景：

• 大型代码库的架构理解与代码搜索。
• AI 编程代理需要快速获取代码上下文以减少 token 消耗。
• 需要跨文件追踪调用链和影响分析的开发场景。

不适用场景：

• 小型项目（文件数少）可能无法体现性能优势。
• 需要实时动态分析（如反射、动态分发）的代码。
• 对隐私要求极高，不允许任何本地索引的场景。

技术架构与依赖

• 核心引擎：Rust 编写的解析内核，使用 tree-sitter 语法解析。
• 存储：本地 SQLite 数据库（.codegraph/codegraph.db），支持 FTS5 全文搜索。
• 运行时：自带 Node.js 运行时，无需额外安装。
• 依赖：无外部服务，无 API 密钥。

安装与快速开始

# 安装 CLI（无需 Node.js）
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

# 或使用 npm
npm i -g @colbymchenry/codegraph

# 连接 AI 代理
codegraph install

# 初始化项目并构建索引
cd your-project
codegraph init

典型使用方法

# 搜索符号
codegraph query "UserService"

# 探索相关代码
codegraph explore "How does a request reach the database?"

# 查看调用者/被调用者
codegraph callers "UserService.getUser"
codegraph callees "UserService.getUser"

# 影响分析
codegraph impact "UserService"

# 查找受影响的测试文件
codegraph affected src/utils.ts

配置与部署要点

• 零配置：默认无需配置，自动识别语言和排除目录。
• 自定义扩展名：通过 codegraph.json 映射非标准文件扩展名。
• 排除/包含目录：通过 codegraph.json 的 exclude 和 include 字段控制。
• 环境变量：如 CODEGRAPH_WATCH_DEBOUNCE_MS 调整监听延迟，CODEGRAPH_NO_DAEMON=1 禁用后台守护进程。
• 部署：支持 Windows、macOS、Linux 的 x64 和 arm64 架构。

限制、风险与许可证

• 限制：静态分析无法覆盖所有动态行为（如反射、动态分发）。
• 风险：索引可能因代码变更而漂移，需定期重建（codegraph index）。
• 许可证：MIT。

官方链接

• GitHub 仓库
• 文档与网站
• npm 包

信息来源和分析时间

• 信息来源：GitHub 仓库 README、文档、基准测试报告。
• 分析时间：2026-08-06。