CodeGraph：为 AI 编码智能体预建语义知识图谱，大幅缩减 Token 与工具调用
CodeGraph 是一个针对 AI 编码智能体（如 Claude Code、Cursor 等）的本地代码知识图谱工具。它通过 tree-sitter 静态解析源码，将符号关系、调用链和代码结构预先索引至本地 SQLite 数据库，供智能体直接查询，从而替代传统耗时的 grep 和文件读取搜索。根据在 7 个真实项目上的基准测试，集成后平均可降低 25% 的成本、减少 62% 的工具调用，并能实现跨框架路由识别和 iOS/React Native 混合桥接解析。该项目完全本地运行，无需外部服务或 API 密钥，适合追求降低 Token 消耗和提升编码效率的工程师。
CodeGraph is a fully local, pre-indexed semantic knowledge graph that plugs directly into AI coding agents like Claude Code, Cursor, and Gemini. Instead of making your coding agent grep and read through files to understand a codebase, CodeGraph gives it a ready-made map of symbols, calls, imports, and web routes. The immediate benefit: ~25% lower cost, ~57% fewer tokens consumed, and ~62% fewer tool calls on average, verified across seven real-world OSS codebases. Everything stays on your machine — just a single SQLite file in .codegraph/.
CodeGraph 是一个完全本地化的、预建的知识图谱，直连 Claude Code、Cursor、Gemini 等 AI 编码 Agent。它预先分析好项目的符号关系、调用链、导入链接甚至 Web 路由——Agent 不用再 grep、读文件逐个摸索，直接查图就能拿到答案。实际收益是平均成本降低 ~25%、token 消耗减少 ~57%、工具调用次数减少 ~62%（基于 7 个真实开源代码库的基准测试）。完全离线，只在 .codegraph/ 里放一个 SQLite 文件。
When AI coding agents like Claude Code explore a new codebase, they typically spawn Explore sub-agents that run grep, glob, and Read calls. Each tool invocation costs tokens, and the whole discovery phase can eat up the majority of the agent's budget. CodeGraph replaces that blind exploration: the key structural questions — "Who calls this?", "How does X reach Y?", "What routes lead to this handler?" — can be answered in one or two direct graph queries instead of a dozen file scans. In benchmarks, this often means zero file reads are needed to answer an architecture question.
AI 编码 Agent（比如 Claude Code）探索陌生项目时，通常会派 Explore 子代理到处 grep、glob、读文件。每一次工具调用都在烧 token，发现阶段的消耗经常占掉请求的大头。CodeGraph 把这个过程替代掉："谁调用了它？""X 是怎么到达 Y 的？""哪些 URL 会打到这里？"——以前要扫十几份文件，现在一到两次图查询就能直接出结果。基准测试中，回答同类架构问题往往一次文件读取都不需要。
CodeGraph provides six core primitives over its graph: context building (entry points and related snippets in one call), full-text search (powered by FTS5), callers/callees/impact analysis (trace upstream, downstream, and the blast radius of a change), web-framework route recognition (14 frameworks, linking URL patterns to their handlers), and cross-language iOS/React Native/Expo bridging (swift↔objc, JS↔native modules, Fabric/TurboModules, etc.). The MCP server exposes these as nine tools — e.g. codegraph_context, codegraph_trace, codegraph_impact — so the agent can pick the right one by intent.
CodeGraph 在图之上提供了六大类能力：上下文构建（一次调用给入口点和关联代码片段）、全文搜索（基于 FTS5）、上下游与影响分析（追踪调用者、被调用者及修改影响半径）、Web 框架路由识别（覆盖 14 种框架，链接 URL 模式与处理函数）、以及跨语言的 iOS/React Native/Expo 桥接（swift↔objc、JS↔原生模块、Fabric/TurboModules 等）。MCP 服务器将这些能力暴露为 9 个工具，比如 codegraph_context、codegraph_trace、codegraph_impact，Agent 可以根据意图直接选择。
CodeGraph has three stages: Extraction — tree-sitter parses sources into ASTs, and language-specific queries pull out nodes (functions, classes, methods) and edges (calls, imports, inheritance). Storage — everything lands in a local SQLite database (.codegraph/codegraph.db) with FTS5 full-text search. Resolution — references are resolved post-extraction: function calls → definitions, imports → source files, plus framework-specific patterns and cross-language bridges. Once the MCP server starts, a native file watcher (FSEvents / inotify / ReadDirectoryChangesW) keeps the index in sync as you code, with a 2-second debounce; if a file is pending sync, the MCP response includes a staleness banner so the agent knows to read it directly.
CodeGraph 分三阶段工作：提取——tree-sitter 将源码解析为 AST，语言专属查询提取节点（函数、类、方法）和边（调用、导入、继承）。存储——全部写入本地 SQLite 数据库（.codegraph/codegraph.db），启用 FTS5 全文搜索。解析——提取后引用被解析：函数调用→定义、导入→源文件，外加框架特有模式和跨语言桥接。MCP 服务启动后，原生文件监视器（FSEvents / inotify / ReadDirectoryChangesW）以 2 秒防抖自动同步索引；如果文件等待同步，MCP 响应会带“⚠️”横幅提示 Agent 直接读文件。
CodeGraph ships a self-contained build — no Node.js required — and supports macOS, Linux, and Windows. The one-liner installer auto-detects your coding agents (Claude Code, Cursor, Codex, etc.) and wires up the MCP config. After restarting the agent, you initialize a project with two words:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
# Initialize a project
cd your-project
codegraph init -i
That's it — when the agent sees a .codegraph/ directory, it uses the graph tools automatically.
CodeGraph 自带运行时，无需安装 Node.js，支持 macOS、Linux、Windows 三平台。一条安装命令自动检测你的编码 Agent（Claude Code、Cursor、Codex 等）并写入 MCP 配置。重启 Agent 后，进入项目执行两词命令即可：
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1 | iex
# 初始化项目
cd your-project
codegraph init -i
完成——Agent 检测到 .codegraph/ 目录后自动使用图工具。
CodeGraph shines on medium to large codebases where discovery costs dominate. On VS Code (~10k files) it delivered 33% cost savings; on small repos like Gin (~110 files) the gain narrowed to 15% — still positive, but narrow because a modern model's native search is already cheap. It works best when the agent answers structural questions directly using the graph; if the agent falls back to spawning file-reading sub-agents, CodeGraph can become overhead. The tool is zero-config, skips third-party directories (node_modules, vendor, etc.), and respects .gitignore out of the box. For sandboxed environments that can't use the file watcher, manual codegraph sync is needed. CodeGraph only knows what its tree-sitter extractors can parse — cross-language bridges are tagged as heuristic, and languages like Objective-C++ may parse incompletely.
CodeGraph 在大中型项目上收益最明显——VS Code（约 1 万文件）基准测试中节省了 33% 的成本；小型项目如 Gin（~110 文件）收益收窄到 15%，但依然正向，因为现代模型原生搜索本身也够快。核心前提是 Agent 自身直接调用图工具回答结构性问题；如果 Agent 退回到派生子代理读文件，CodeGraph 反而会成为额外开销。项目零配置，自动跳过第三方目录（node_modules、vendor 等），默认遵循 .gitignore。沙箱环境下无法使用文件监视器时需要手动运行 codegraph sync。CodeGraph 只知道 tree-sitter 能解析的结构——所有跨语言桥接都标记为“启发式”（heuristic），Objective-C++ 这类混合语言也可能解析不完全。