Codehelper

Codehelper

面向 AI 编码助手的本地优先代码仓库智能工具。

Codehelper 会为你机器上的 Git 代码仓库建立索引，构建符号与调用图，并提供 60+ 个 MCP 工具，让 Cursor、Claude Code、Codex 和其他 MCP 客户端能够搜索、理解并安全地修改你的代码，而无需将整个代码仓库上传到云端大模型。

---

使用 Codehelper 的三个理由

1. 了解项目的 Agent — 在本地搜索符号、调用方和影响范围，而不是对整个文件运行 grep。
2. 离线可用 — 无需 API 密钥；代码留在你的机器上。
3. 适配你的编辑器 — 为 Cursor、Claude Code 和 Codex 提供 MCP；每个代码仓库只需运行一次 codehelper init。

---

安装

Linux / macOS（推荐）：

curl -fsSL https://raw.githubusercontent.com/VeyrForge/codehelper/main/scripts/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

从源代码构建（需要 Go 1.25+、CGO 和 C 编译器）：

git clone https://github.com/VeyrForge/codehelper.git && cd codehelper
npm run build

GitHub Releases 上提供预构建的 3.0.3 安装包（Linux、macOS、Windows），其中包含 codehelper、MCP 服务、ge 1.1.1 和 greencompress 1.1.1：GitHub Releases。

更新： 默认情况下，codehelper upgrade 会从 VeyrForge/codehelper 下载最新版本。使用 --repo owner/name 或 CODEHELPER_UPGRADE_REPO 可覆盖更新来源。codehelper update 会从本地 Git 检出版本重新构建，并可在任意目录下运行（会记住源代码路径，也可使用 CODEHELPER_SOURCE / update /path/to/codehelper）。

---

30 秒示例

cd your-git-repo
codehelper init
codehelper help tools --main

首次运行 init 后，重新加载 Cursor 或 Claude Code；然后每个会话调用一次 project_context，让 Agent 了解有哪些工具可用，以及索引有多新。

---

查看运行效果

目前尚无内置演示视频——以下是典型的首次会话：

$ codehelper init
init: ready — index + watch daemon active

$ codehelper status
symbols: 1247  edges: 3891  freshness: current

$ codehelper help tools --main
  project_context  bootstrap tool catalog + index stats
  query            search the symbol graph
  context          source + callers + callees
  impact           blast radius before you edit

基准测试方法（不虚构竞品数据）：docs/BENCHMARK_COMPARISON.md。

---

支持的平台

平台	安装方式	备注
Linux	scripts/install.sh	完整支持；主要 CI 目标平台
macOS	scripts/install.sh	通用版及按架构划分的发布二进制文件
Windows	scripts/install.ps1	支持 x64

客户端	配置
Cursor	通过 codehelper init 为每个项目生成 .mcp.json
Claude Code	在 ~/.claude.json 中添加托管区块
Codex	读取生成的 AGENTS.md

---

工作原理

层	技术
索引	tree-sitter 解析器 + SQLite 符号/调用图
搜索	BM25 + 三元组 + 调用图排序（可选本地语义重排 — docs/LOCAL_EMBED.md）
MCP 传输	stdio（默认）或 HTTP（codehelper mcp --http :8765）
可选本地模型	Green Engine 嵌入/聊天 + Green Compress 权重

init 会为仓库建立索引、启动监视守护进程、为编辑器配置 MCP，并写入 Agent 规则。可选本地仪表板：ge ui serve → http://127.0.0.1:8780

完整工具参考：docs/MCP_TOOLS.md

---

基准测试

竞品比较的方法（测试组、指标、基准层级 — 不编造竞品数据）请参阅 docs/BENCHMARK_COMPARISON.md。测得的数据只能来自可复现的本地测试框架运行结果。

注意事项：许多已发布的表格属于自身仓库（此代码树）或轻量方法配对定位探测（MCP 与主机文件遍历）。这些数据并非端到端编码助手问题修复率。优先使用多基准仓库留出测试（CODEHELPER_TESTBEDS），竞品数据只能通过本地重新运行来填写。

# One recipe: prepare + paired + dated report
scripts/testbeds-all.sh
scripts/testbeds-all.sh fixture   # always-safe, no beds

布局以及准备/评测用法：docs/TESTBEDS.md。

---

文档

• docs/MCP_TOOLS.md — MCP 工具参考
• docs/BENCHMARK_COMPARISON.md — 基准测试方法 + 测试框架（不编造竞品数据）
• CHANGELOG.md — 版本历史
• third_party/README.md — 随附的 Green 技术栈二进制文件

---

局限性

• 索引需要 git 仓库。
• 从源代码构建需要 CGO 和 C 编译器（tree-sitter）。
• 语义重排：可选的轻量本地嵌入路径（bash scripts/install-local-embed.sh / codehelper green init-embed）——请参阅 docs/LOCAL_EMBED.md。内容增强需要可选的本地模型服务（Green Engine）。
• Windows arm64 CI 为实验性/非阻塞（windows-11-arm）。发布版本始终提供 Windows amd64；只有 amd64 和 arm64 构建均成功时，才会发布 *_windows_universal.zip（v3.0.2 及更早版本的历史 *_windows_universal.zip 资源大小与 amd64 版本相同，不应视为真正的通用版本）。

---

参与贡献

欢迎在官方 VeyrForge/codehelper 仓库提交 Bug 报告、基准测试结果、兼容性说明和改进建议。

欢迎提交改进 Codehelper 的拉取请求。参与贡献即表示你同意贡献者许可协议。你也可以依据 BUSL-1.1 的附加使用授权，为自己的部署保留私有/内部 Fork。不得向第三方提供托管版 Codehelper（或实质上相似的替代品），也不得将其作为竞争产品提供。请参阅许可与允许的使用方式和 LICENSE-FAQ.md。

---

公开发布历史

请参阅 CHANGELOG.md 和 GitHub Releases。

---

许可证与允许的使用方式

Codehelper 采用 Business Source License 1.1（BUSL-1.1）作为源代码可用许可。在变更许可证生效前，它不属于 OSI 开源软件。

你可以：

• 出于个人用途或内部业务目的（包括代表你行事的员工和承包商），使用并运行 Codehelper（包括在生产环境中）
• 出于上述相同目的复制、修改并创建衍生作品——无需将更改贡献回来
• 使用 Codehelper 为自己或客户开发、测试、维护、审查或运营软件（但不得将 Codehelper 本身作为产品或服务提供）
• 研究已发布的源代码

在变更许可证生效前，你不得：

• 向第三方提供 Codehelper 或修改版，将其作为托管、管理、嵌入或分发的产品或服务，且其主要用途是提供与 Codehelper 实质相似、可替代 Codehelper 的功能
• 销售更名后的分支，或将 Codehelper 作为另一款付费产品的主要功能嵌入其中，而未取得商业许可

变更日期： 2029-07-24——在该日期，或本版本首次公开依据 BSL 分发的第四个周年纪念日（以较早者为准），本版本将依据 Apache License 2.0 提供。

教程和博客文章可以摘录已发布源代码中的简短示例片段用于说明，前提是不得将软件重新分发为竞争产品，也不得在变更日期之前暗示其已获 OSI 开源许可。

如需商业再分发、OEM 许可或其他未在上述内容中涵盖的用途，请联系 [email protected]。

本节为通俗易懂的摘要。具有约束力的条款载于 LICENSE。解释性问答：LICENSE-FAQ.md。另请参阅 CLA.md、SECURITY.md、docs/PERMISSIONS.md 和 docs/ROADMAP.md。