CodeGraph 使用指南colbymchenry/codegraph— 为编程智能体预构建的代码知识图谱更少 Token、更少工具调用100% 本地运行。一、是什么CodeGraph 把你的代码库解析成一张语义知识图谱节点 函数/类/方法边 调用/导入/继承存入本地 SQLite 数据库。AI 编程智能体Claude Code、Cursor、Codex CLI 等直接查询图谱而不是反复用 grep/Read 扫描文件。核心数据7个真实代码库测试平均35% 成本降低 · 57% Token 减少 · 46% 更快的响应 · 71% 更少的工具调用。二、安装WindowsPowerShellirmhttps://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1|iexmacOS / Linuxcurl-fsSLhttps://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh|sh已有 Node.js 环境npx colbymchenry/codegraph# 零安装直接使用npminstall-gcolbymchenry/codegraph# 全局安装无需 Node.js安装脚本自带运行时无需编译。三、快速上手3 步第 1 步安装并配置智能体codegraphinstall--yes交互式安装器会自动检测你已安装的编程智能体Claude Code / Cursor / Codex CLI / opencode / Hermes Agent并自动配置 MCP 服务器连接和指令文件。第 2 步在项目目录中初始化cd你的项目目录 codegraph init-i这会构建项目的知识图谱索引.codegraph/codegraph.db。索引自动遵循.gitignorenode_modules等不会进入图谱。第 3 步重启智能体重启 Claude Code / Cursor / Codex CLI 等工具MCP 服务器会自动加载。之后只要项目里有.codegraph/目录智能体就会自动使用 CodeGraph 工具。四、核心命令速查命令作用codegraph install运行交互式安装器codegraph uninstall从所有智能体中移除 CodeGraphcodegraph init [路径]在项目中初始化-i交互模式codegraph uninit [路径]从项目中移除 CodeGraphcodegraph index [路径]全量索引--force强制重建codegraph sync [路径]增量更新索引codegraph status [路径]查看索引统计信息codegraph query 关键词按名称搜索符号codegraph context 任务描述为 AI 构建上下文codegraph callers 符号名查找谁调用了某函数codegraph callees 符号名查找某函数调用了谁codegraph impact 符号名变更影响分析codegraph affected [文件...]查找受改动影响的测试文件codegraph serve --mcp启动 MCP 服务器五、MCP 工具详解智能体可用智能体在对话中可调用以下 10 个工具工具用途典型场景codegraph_context一次调用获取入口点、相关符号和代码片段架构理解任务的首选codegraph_trace追踪两个符号之间的完整调用路径“X 是如何调用到 Y 的”codegraph_search按名称搜索符号“找到 UserService”codegraph_callers找出谁调用了某个函数了解调用方codegraph_callees找出函数调用了什么了解依赖codegraph_impact分析修改某个符号的影响范围改动前风险评估codegraph_explore批量获取多个相关符号的源码批量查看相关代码codegraph_node获取单个符号详情查看函数签名codegraph_files获取索引的文件结构比文件系统扫描更快codegraph_status检查索引状态和统计确认图谱是否最新六、实际使用示例场景 1理解架构对 Claude Code 说“How does the extension host communicate with the main process?”智能体会先用codegraph_context定位相关区域再用codegraph_trace追踪调用路径一次对话即可获得完整答案而不是启动多个 Explore 子代理去扫描文件。场景 2影响分析先在终端用 CLI 分析codegraph impact handleRequest输出该函数的所有调用方、被调用方及其依赖链评估改动风险。场景 3CI 集成#!/usr/bin/env bash# 只运行受影响的测试AFFECTED$(gitdiff--name-only HEAD|codegraph affected--stdin--quiet)if[-n$AFFECTED];thennpx vitest run$AFFECTEDfi七、语言支持19TypeScript · JavaScript · Python · Go · Rust · Java · C# · PHP · Ruby · C · C · Swift · Kotlin · Scala · Dart · Svelte · Vue · Lua · Luau八、工作原理你的代码 → tree-sitter 解析 AST → 提取节点(函数/类)和边(调用/导入) → SQLite 存储 FTS5 全文搜索 → 引用解析(调用→定义) → 原生文件监视器自动同步(2秒防抖) → MCP 服务器暴露工具给智能体九、手动配置高级如需手动配置在~/.claude.json中添加{mcpServers:{codegraph:{type:stdio,command:codegraph,args:[serve,--mcp]}}}~/.claude/settings.json中添加自动权限{permissions:{allow:[mcp__codegraph__codegraph_search,mcp__codegraph__codegraph_context,mcp__codegraph__codegraph_callers,mcp__codegraph__codegraph_callees,mcp__codegraph__codegraph_impact,mcp__codegraph__codegraph_node,mcp__codegraph__codegraph_status,mcp__codegraph__codegraph_files]}}十、常见问题Q索引慢怎么办A检查node_modules等大目录是否已在.gitignore中。使用--quiet减少输出开销。QMCP 连接不上A确保项目已codegraph init确认配置路径正确手动运行codegraph serve --mcp测试。Q符号缺失AMCP 服务器会自动同步等待几秒。手动运行codegraph sync。确认文件语言是否在支持列表中。Q如何卸载Acodegraph uninstall从智能体中移除配置codegraph uninit删除项目中的.codegraph/目录。GitHub 仓库https://github.com/colbymchenry/codegraph许可证MIT本周新增 Star18,136 ·总 Star23,249
CodeGraph使用指南
CodeGraph 使用指南colbymchenry/codegraph— 为编程智能体预构建的代码知识图谱更少 Token、更少工具调用100% 本地运行。一、是什么CodeGraph 把你的代码库解析成一张语义知识图谱节点 函数/类/方法边 调用/导入/继承存入本地 SQLite 数据库。AI 编程智能体Claude Code、Cursor、Codex CLI 等直接查询图谱而不是反复用 grep/Read 扫描文件。核心数据7个真实代码库测试平均35% 成本降低 · 57% Token 减少 · 46% 更快的响应 · 71% 更少的工具调用。二、安装WindowsPowerShellirmhttps://raw.githubusercontent.com/colbymchenry/codegraph/main/install.ps1|iexmacOS / Linuxcurl-fsSLhttps://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh|sh已有 Node.js 环境npx colbymchenry/codegraph# 零安装直接使用npminstall-gcolbymchenry/codegraph# 全局安装无需 Node.js安装脚本自带运行时无需编译。三、快速上手3 步第 1 步安装并配置智能体codegraphinstall--yes交互式安装器会自动检测你已安装的编程智能体Claude Code / Cursor / Codex CLI / opencode / Hermes Agent并自动配置 MCP 服务器连接和指令文件。第 2 步在项目目录中初始化cd你的项目目录 codegraph init-i这会构建项目的知识图谱索引.codegraph/codegraph.db。索引自动遵循.gitignorenode_modules等不会进入图谱。第 3 步重启智能体重启 Claude Code / Cursor / Codex CLI 等工具MCP 服务器会自动加载。之后只要项目里有.codegraph/目录智能体就会自动使用 CodeGraph 工具。四、核心命令速查命令作用codegraph install运行交互式安装器codegraph uninstall从所有智能体中移除 CodeGraphcodegraph init [路径]在项目中初始化-i交互模式codegraph uninit [路径]从项目中移除 CodeGraphcodegraph index [路径]全量索引--force强制重建codegraph sync [路径]增量更新索引codegraph status [路径]查看索引统计信息codegraph query 关键词按名称搜索符号codegraph context 任务描述为 AI 构建上下文codegraph callers 符号名查找谁调用了某函数codegraph callees 符号名查找某函数调用了谁codegraph impact 符号名变更影响分析codegraph affected [文件...]查找受改动影响的测试文件codegraph serve --mcp启动 MCP 服务器五、MCP 工具详解智能体可用智能体在对话中可调用以下 10 个工具工具用途典型场景codegraph_context一次调用获取入口点、相关符号和代码片段架构理解任务的首选codegraph_trace追踪两个符号之间的完整调用路径“X 是如何调用到 Y 的”codegraph_search按名称搜索符号“找到 UserService”codegraph_callers找出谁调用了某个函数了解调用方codegraph_callees找出函数调用了什么了解依赖codegraph_impact分析修改某个符号的影响范围改动前风险评估codegraph_explore批量获取多个相关符号的源码批量查看相关代码codegraph_node获取单个符号详情查看函数签名codegraph_files获取索引的文件结构比文件系统扫描更快codegraph_status检查索引状态和统计确认图谱是否最新六、实际使用示例场景 1理解架构对 Claude Code 说“How does the extension host communicate with the main process?”智能体会先用codegraph_context定位相关区域再用codegraph_trace追踪调用路径一次对话即可获得完整答案而不是启动多个 Explore 子代理去扫描文件。场景 2影响分析先在终端用 CLI 分析codegraph impact handleRequest输出该函数的所有调用方、被调用方及其依赖链评估改动风险。场景 3CI 集成#!/usr/bin/env bash# 只运行受影响的测试AFFECTED$(gitdiff--name-only HEAD|codegraph affected--stdin--quiet)if[-n$AFFECTED];thennpx vitest run$AFFECTEDfi七、语言支持19TypeScript · JavaScript · Python · Go · Rust · Java · C# · PHP · Ruby · C · C · Swift · Kotlin · Scala · Dart · Svelte · Vue · Lua · Luau八、工作原理你的代码 → tree-sitter 解析 AST → 提取节点(函数/类)和边(调用/导入) → SQLite 存储 FTS5 全文搜索 → 引用解析(调用→定义) → 原生文件监视器自动同步(2秒防抖) → MCP 服务器暴露工具给智能体九、手动配置高级如需手动配置在~/.claude.json中添加{mcpServers:{codegraph:{type:stdio,command:codegraph,args:[serve,--mcp]}}}~/.claude/settings.json中添加自动权限{permissions:{allow:[mcp__codegraph__codegraph_search,mcp__codegraph__codegraph_context,mcp__codegraph__codegraph_callers,mcp__codegraph__codegraph_callees,mcp__codegraph__codegraph_impact,mcp__codegraph__codegraph_node,mcp__codegraph__codegraph_status,mcp__codegraph__codegraph_files]}}十、常见问题Q索引慢怎么办A检查node_modules等大目录是否已在.gitignore中。使用--quiet减少输出开销。QMCP 连接不上A确保项目已codegraph init确认配置路径正确手动运行codegraph serve --mcp测试。Q符号缺失AMCP 服务器会自动同步等待几秒。手动运行codegraph sync。确认文件语言是否在支持列表中。Q如何卸载Acodegraph uninstall从智能体中移除配置codegraph uninit删除项目中的.codegraph/目录。GitHub 仓库https://github.com/colbymchenry/codegraph许可证MIT本周新增 Star18,136 ·总 Star23,249
