codegraph是专为AI编码代理打造的本地代码知识图谱引擎彻底解决了AI理解大型代码库时反复扫描文件、Token消耗巨大、上下文混乱的行业痛点。它预先索引整个代码库的符号关系、调用图和结构信息让Claude Code、Cursor等AI代理直接查询结构化知识而非逐行扫描文件平均减少57% Token消耗、46%响应时间和71%工具调用是大型项目AI开发的必备基础设施。一、项目核心信息项目地址github.com/colbymchenry/codegraph开发语言TypeScript核心定位AI编码代理的本地代码搜索引擎与知识图谱三大革命性优势预索引知识图谱自动提取代码库的类、函数、变量、调用关系和依赖结构极致成本优化官方实测减少57% Token、46%时间、71%工具调用总成本降低35%100%本地运行所有索引和查询都在本地完成代码永不离开你的电脑适用场景Claude Code深度用户、大型代码库分析、AI编码成本优化、多语言项目开发二、环境要求Node.js18.17.0 版本推荐20.x LTS包管理器npm 9 或 pnpm 8支持的AI客户端✅Claude Code原生集成体验最佳✅ Cursor 0.45✅ Windsurf 1.5✅ VS Code GitHub Copilot✅ DeepSeek-TUI支持的编程语言TypeScript/JavaScript、Python、Java、C/C、Rust、Go、C#操作系统Windows 10/11、macOS 12、Linux(Ubuntu 22.04)硬件要求8GB以上内存推荐16GB索引10万行代码约需1GB磁盘空间三、安装方法3种方案方案1NPM全局安装推荐所有用户# 使用npm安装npminstall-gcodegraph/cli# 使用pnpm安装推荐速度更快pnpmadd-gcodegraph/cli方案2从源码安装开发者gitclone https://github.com/colbymchenry/codegraph.gitcdcodegraphpnpminstallpnpmbuildpnpmlink--global方案3VS Code扩展安装打开VS Code扩展市场搜索codegraph点击安装安装完成后会自动安装CLI工具四、初始配置与索引生成1. 验证安装打开终端输入以下命令验证安装是否成功codegraph--version如果显示版本号说明安装成功。2. 生成项目索引核心步骤进入你的项目根目录运行以下命令生成代码知识图谱# 生成当前项目的完整索引codegraph index# 只索引指定目录codegraph index src/ lib/# 排除指定目录codegraph index--excludenode_modules/ dist/ build/# 显示详细索引过程codegraph index--verbose索引过程说明扫描项目中的所有代码文件解析抽象语法树(AST)提取所有符号类、函数、变量、接口等构建调用图和依赖关系生成向量化索引并保存到本地索引完成后会显示统计信息索引时间参考小型项目(1万行)10-30秒中型项目(1-10万行)1-5分钟大型项目(10-100万行)5-30分钟超大型项目(100万行)30分钟以上3. 配置AI客户端Claude Code 配置原生集成无需额外设置Claude Code会自动检测项目中的codegraph索引并使用无需任何手动配置。当你询问关于代码库的问题时Claude会自动查询知识图谱而不是扫描文件。Cursor 配置打开Cursor设置找到「AI」→「高级设置」开启「Enable codegraph integration」重启CursorVS Code GitHub Copilot 配置安装codegraph VS Code扩展打开扩展设置开启「Enable Copilot integration」重启VS Code五、核心功能使用1. 命令行查询你可以直接在终端中查询代码知识图谱# 查询某个函数的定义和调用位置codegraph queryfind all calls to the sendData function# 查询某个类的继承关系codegraph queryshow the inheritance hierarchy of the User class# 查询所有使用了某个依赖的文件codegraph querywhich files import the axios library# 查询项目的整体架构codegraph querydescribe the overall architecture of this project2. 在AI客户端中使用这是最常用的方式直接在AI聊天中提问AI会自动使用codegraph索引示例1查询函数调用关系帮我分析一下这个项目中login函数的调用流程没有codegraph时AI会扫描所有文件查找login函数的定义和所有调用位置可能需要多次工具调用消耗大量Token。有codegraph时AI直接从索引中获取完整的调用图一次查询即可得到答案速度快10倍以上。示例2代码重构我想重构UserService类帮我找出所有依赖这个类的地方示例3Bug定位用户报告登录功能有时会失败帮我分析可能的原因3. 可视化代码图谱codegraph提供了一个Web界面可以可视化查看代码的结构和关系# 启动Web可视化界面codegraph serve访问http://localhost:3000即可打开Web界面你可以查看项目的整体架构图浏览所有类和函数的关系查看调用图和依赖图搜索符号和文件导出图谱为图片或PDF4. 零文件读取模式对于大型代码库你可以开启零文件读取模式让AI完全依赖codegraph索引回答问题完全不读取任何文件# 开启零文件读取模式codegraph configsetzero_file_readtrue开启后AI将不会调用任何文件读取工具所有信息都来自预先生成的索引进一步提升速度和降低成本。六、性能与成本对比官方在一个包含50万行代码的中型项目上进行了测试结果如下指标无codegraph有codegraph提升幅度平均响应时间48秒26秒46%更快平均Token消耗12,4005,30057%更少平均工具调用次数7.2次2.1次71%更少平均每次查询成本$0.037$0.02435%更便宜大文件查询成功率62%98%58%更高七、高级使用技巧1. 增量索引当你修改了代码后不需要重新生成整个索引只需运行增量索引# 只索引修改过的文件codegraph index--incremental# 自动监控文件变化实时更新索引codegraphwatch2. 多项目管理codegraph支持管理多个项目的索引# 列出所有已索引的项目codegraph projects list# 切换到另一个项目codegraph projects switch my-other-project# 删除项目索引codegraph projects delete old-project3. 自定义配置你可以创建一个codegraph.config.json文件来自定义索引行为{include:[src/**/*.ts,src/**/*.tsx],exclude:[**/node_modules/**,**/dist/**,**/*.test.ts],indexer:{typescript:{enableTypeChecking:true},python:{pythonPath:/usr/bin/python3}},vector:{dimension:1536,model:all-MiniLM-L6-v2}}4. 导出索引你可以将索引导出为JSON文件与团队共享# 导出索引codegraphexportindex.json# 导入索引codegraphimportindex.json八、常见问题与解决方案索引生成失败检查Node.js版本是否≥18.17.0确保有足够的磁盘空间尝试增加Node.js内存限制export NODE_OPTIONS--max-old-space-size8192排除大型二进制文件和第三方库目录AI不使用codegraph索引确认AI客户端版本支持codegraph集成重启AI客户端重新生成索引codegraph index --force在提问时明确要求使用codegraph使用codegraph索引回答这个问题查询结果不准确更新索引codegraph index --incremental尝试更具体的查询检查是否有文件被排除在索引之外开启详细日志codegraph config set log_level debug性能问题使用增量索引而不是全量索引排除不必要的文件和目录升级到16GB以上内存使用SSD存储索引文件九、重要注意事项隐私保护所有索引和查询都在本地完成你的代码永远不会上传到任何服务器完全符合企业安全要求定期更新索引代码修改后记得运行增量索引确保AI获取的是最新的信息大型项目优化对于超过100万行的项目建议分模块索引只索引你当前工作的模块不要过度依赖codegraph是辅助工具对于非常复杂的逻辑AI可能仍然需要查看具体的文件内容开源协议本项目采用MIT许可证可以自由使用和修改社区支持遇到问题可以在GitHub Issues或Discord社区寻求帮助
【GitHub开源】codegraph 完整使用教程（2026最新版）
发布时间：2026/5/26 11:45:05
codegraph是专为AI编码代理打造的本地代码知识图谱引擎彻底解决了AI理解大型代码库时反复扫描文件、Token消耗巨大、上下文混乱的行业痛点。它预先索引整个代码库的符号关系、调用图和结构信息让Claude Code、Cursor等AI代理直接查询结构化知识而非逐行扫描文件平均减少57% Token消耗、46%响应时间和71%工具调用是大型项目AI开发的必备基础设施。一、项目核心信息项目地址github.com/colbymchenry/codegraph开发语言TypeScript核心定位AI编码代理的本地代码搜索引擎与知识图谱三大革命性优势预索引知识图谱自动提取代码库的类、函数、变量、调用关系和依赖结构极致成本优化官方实测减少57% Token、46%时间、71%工具调用总成本降低35%100%本地运行所有索引和查询都在本地完成代码永不离开你的电脑适用场景Claude Code深度用户、大型代码库分析、AI编码成本优化、多语言项目开发二、环境要求Node.js18.17.0 版本推荐20.x LTS包管理器npm 9 或 pnpm 8支持的AI客户端✅Claude Code原生集成体验最佳✅ Cursor 0.45✅ Windsurf 1.5✅ VS Code GitHub Copilot✅ DeepSeek-TUI支持的编程语言TypeScript/JavaScript、Python、Java、C/C、Rust、Go、C#操作系统Windows 10/11、macOS 12、Linux(Ubuntu 22.04)硬件要求8GB以上内存推荐16GB索引10万行代码约需1GB磁盘空间三、安装方法3种方案方案1NPM全局安装推荐所有用户# 使用npm安装npminstall-gcodegraph/cli# 使用pnpm安装推荐速度更快pnpmadd-gcodegraph/cli方案2从源码安装开发者gitclone https://github.com/colbymchenry/codegraph.gitcdcodegraphpnpminstallpnpmbuildpnpmlink--global方案3VS Code扩展安装打开VS Code扩展市场搜索codegraph点击安装安装完成后会自动安装CLI工具四、初始配置与索引生成1. 验证安装打开终端输入以下命令验证安装是否成功codegraph--version如果显示版本号说明安装成功。2. 生成项目索引核心步骤进入你的项目根目录运行以下命令生成代码知识图谱# 生成当前项目的完整索引codegraph index# 只索引指定目录codegraph index src/ lib/# 排除指定目录codegraph index--excludenode_modules/ dist/ build/# 显示详细索引过程codegraph index--verbose索引过程说明扫描项目中的所有代码文件解析抽象语法树(AST)提取所有符号类、函数、变量、接口等构建调用图和依赖关系生成向量化索引并保存到本地索引完成后会显示统计信息索引时间参考小型项目(1万行)10-30秒中型项目(1-10万行)1-5分钟大型项目(10-100万行)5-30分钟超大型项目(100万行)30分钟以上3. 配置AI客户端Claude Code 配置原生集成无需额外设置Claude Code会自动检测项目中的codegraph索引并使用无需任何手动配置。当你询问关于代码库的问题时Claude会自动查询知识图谱而不是扫描文件。Cursor 配置打开Cursor设置找到「AI」→「高级设置」开启「Enable codegraph integration」重启CursorVS Code GitHub Copilot 配置安装codegraph VS Code扩展打开扩展设置开启「Enable Copilot integration」重启VS Code五、核心功能使用1. 命令行查询你可以直接在终端中查询代码知识图谱# 查询某个函数的定义和调用位置codegraph queryfind all calls to the sendData function# 查询某个类的继承关系codegraph queryshow the inheritance hierarchy of the User class# 查询所有使用了某个依赖的文件codegraph querywhich files import the axios library# 查询项目的整体架构codegraph querydescribe the overall architecture of this project2. 在AI客户端中使用这是最常用的方式直接在AI聊天中提问AI会自动使用codegraph索引示例1查询函数调用关系帮我分析一下这个项目中login函数的调用流程没有codegraph时AI会扫描所有文件查找login函数的定义和所有调用位置可能需要多次工具调用消耗大量Token。有codegraph时AI直接从索引中获取完整的调用图一次查询即可得到答案速度快10倍以上。示例2代码重构我想重构UserService类帮我找出所有依赖这个类的地方示例3Bug定位用户报告登录功能有时会失败帮我分析可能的原因3. 可视化代码图谱codegraph提供了一个Web界面可以可视化查看代码的结构和关系# 启动Web可视化界面codegraph serve访问http://localhost:3000即可打开Web界面你可以查看项目的整体架构图浏览所有类和函数的关系查看调用图和依赖图搜索符号和文件导出图谱为图片或PDF4. 零文件读取模式对于大型代码库你可以开启零文件读取模式让AI完全依赖codegraph索引回答问题完全不读取任何文件# 开启零文件读取模式codegraph configsetzero_file_readtrue开启后AI将不会调用任何文件读取工具所有信息都来自预先生成的索引进一步提升速度和降低成本。六、性能与成本对比官方在一个包含50万行代码的中型项目上进行了测试结果如下指标无codegraph有codegraph提升幅度平均响应时间48秒26秒46%更快平均Token消耗12,4005,30057%更少平均工具调用次数7.2次2.1次71%更少平均每次查询成本$0.037$0.02435%更便宜大文件查询成功率62%98%58%更高七、高级使用技巧1. 增量索引当你修改了代码后不需要重新生成整个索引只需运行增量索引# 只索引修改过的文件codegraph index--incremental# 自动监控文件变化实时更新索引codegraphwatch2. 多项目管理codegraph支持管理多个项目的索引# 列出所有已索引的项目codegraph projects list# 切换到另一个项目codegraph projects switch my-other-project# 删除项目索引codegraph projects delete old-project3. 自定义配置你可以创建一个codegraph.config.json文件来自定义索引行为{include:[src/**/*.ts,src/**/*.tsx],exclude:[**/node_modules/**,**/dist/**,**/*.test.ts],indexer:{typescript:{enableTypeChecking:true},python:{pythonPath:/usr/bin/python3}},vector:{dimension:1536,model:all-MiniLM-L6-v2}}4. 导出索引你可以将索引导出为JSON文件与团队共享# 导出索引codegraphexportindex.json# 导入索引codegraphimportindex.json八、常见问题与解决方案索引生成失败检查Node.js版本是否≥18.17.0确保有足够的磁盘空间尝试增加Node.js内存限制export NODE_OPTIONS--max-old-space-size8192排除大型二进制文件和第三方库目录AI不使用codegraph索引确认AI客户端版本支持codegraph集成重启AI客户端重新生成索引codegraph index --force在提问时明确要求使用codegraph使用codegraph索引回答这个问题查询结果不准确更新索引codegraph index --incremental尝试更具体的查询检查是否有文件被排除在索引之外开启详细日志codegraph config set log_level debug性能问题使用增量索引而不是全量索引排除不必要的文件和目录升级到16GB以上内存使用SSD存储索引文件九、重要注意事项隐私保护所有索引和查询都在本地完成你的代码永远不会上传到任何服务器完全符合企业安全要求定期更新索引代码修改后记得运行增量索引确保AI获取的是最新的信息大型项目优化对于超过100万行的项目建议分模块索引只索引你当前工作的模块不要过度依赖codegraph是辅助工具对于非常复杂的逻辑AI可能仍然需要查看具体的文件内容开源协议本项目采用MIT许可证可以自由使用和修改社区支持遇到问题可以在GitHub Issues或Discord社区寻求帮助
