CodeGraph

在 AI 辅助编程日益普及的今天，Claude Code、Cursor 等工具虽然强大，但在处理大型代码库时往往面临一个共同瓶颈：“盲人摸象”式的文件扫描。当 AI 代理需要理解项目架构或追踪函数调用时，它们通常依赖于频繁的 grep、glob 和 Read 操作。这不仅导致大量的 Token 消耗和工具调用延迟，还容易因上下文碎片化而丢失整体视野。

CodeGraph 是一个专为 Claude Code、Cursor、Codex 和 OpenCode 设计的本地语义代码智能增强引擎。它通过构建预索引的知识图谱，让 AI 代理能够“上帝视角”般地即时查询代码结构、符号关系和调用图，从而显著提升编码效率并降低成本。

核心突破：从“文本搜索”到“语义图谱”

CodeGraph 的核心价值在于将非结构化的代码文件转化为结构化的知识图谱：

• 传统模式：AI 代理通过关键词匹配扫描文件，每次探索都需要多次工具调用，既慢又贵。
• CodeGraph 模式：代理只需一次查询，即可获取入口点、相关符号、完整调用链及代码片段。AI 不再是在文件中“寻找”，而是在图谱中“导航”。

性能实测：显著降本增效

在涵盖 7 种编程语言、7 个真实世界开源代码库（如 VS Code、Django、Tokio 等）的基准测试中，CodeGraph 展现了惊人的优化效果：

典型场景表现：

• VS Code (TypeScript, ~10k 文件)：成本降低 35%，工具调用减少 72%。
• Tokio (Rust, ~700 文件)：成本降低 52%，工具调用减少 89%。
• Excalidraw (TypeScript, ~600 文件)：响应速度提升 60%，工具调用减少 86%。

这些数据证明，随着代码库规模的增长，CodeGraph 带来的效率红利愈发明显。

主要特性：全能的本地代码大脑

1. 智能上下文构建

无需让 AI 代理逐个文件读取，CodeGraph 能一次性返回与查询相关的完整上下文，包括定义、引用和依赖关系，极大减少了“探索代理”的无效劳动。

2. 毫秒级全文搜索

基于 SQLite FTS5 引擎，支持在整个代码库中即时按名称查找代码，速度远超传统文件系统搜索。

3. 深度影响分析

在进行代码重构或修改前，可精准追踪任何符号的调用方（Callers）、**被调用方（Callees）**以及完整的影响范围，避免“改一处崩全身”的风险。

4. 框架感知路由

智能识别主流 Web 框架（如 Next.js, Django, Rails 等）的路由文件，并将 URL 模式直接链接到对应的处理函数，方便快速定位业务逻辑。

5. 广泛的语言支持

支持 19+ 种主流编程语言，包括 TypeScript, JavaScript, Python, Go, Rust, Java, C#, PHP, Ruby, C, C++, Swift, Kotlin, Dart, Svelte, Liquid, Pascal/Delphi 等。

6. 100% 本地运行，隐私无忧

• 零外部依赖：所有数据存储在本地 SQLite 数据库中，不离开您的机器。
• 无需 API Key：完全离线可用，无订阅费用，无隐私泄露风险。

工作原理：自动化与实时同步

CodeGraph 的工作流程高度自动化，用户几乎无感知：

1. 提取（Extract）：利用 tree-sitter 将源代码解析为抽象语法树（AST），并通过特定语言的查询提取节点（符号）和边（关系）。
2. 存储（Store）：将所有结构化数据存入本地 SQLite 数据库，并建立 FTS5 全文索引。
3. 解析（Resolve）：智能解析引用关系，包括函数调用、导入来源、类继承以及框架特定的路由模式。
4. 自动同步（Sync）：
   • 文件监视器：使用原生操作系统事件监视项目文件变化。
   • 增量更新：更改经过防抖处理，仅针对源文件进行增量同步。
   • 实时性：图谱随您的编码过程保持最新，无需手动重新索引。

快速开始

CodeGraph 提供了极简的安装和配置体验：

1. 一键安装

npx @colbymchenry/codegraph

交互式安装程序会自动检测并配置您的 AI 代理（Claude Code, Cursor 等）。

2. 初始化项目

进入您的项目根目录，运行初始化命令：

cd your-project
codegraph init -i

系统将自动扫描代码库并构建初始知识图谱。

CodeGraph 不仅仅是一个代码搜索工具，它是 AI 编程代理的**“海马体”**——负责存储和检索复杂的代码记忆。通过引入本地知识图谱，它解决了 AI 在处理大型项目时“记不住、找不准、跑得慢”的核心痛点。