Show HN：为并行 Claude Code 代理设计的本地合并队列

本篇文章介绍了一个名为 Claude Code 合并队列的开源工具，它旨在解决多个 Claude Code 代理并行工作时可能出现的推送冲突、重复构建和测试不稳定问题。该工具在本地运行，无需额外成本，适用于任何 GitHub 仓库。

快速开始

您可以通过 npm 安装：npm install --save-dev claude-code-merge-queue，然后运行 npx claude-code-merge-queue init 进行初始化。

配置

所有配置都存储在一个文件中，例如 claude-code-merge-queue.config.mjs。主要配置项包括：branchPrefix、worktreeSuffix、portBase、integrationBranch、productionBranch、protectedBranches、regenerableFiles、symlinks、buildOutputDirs、checkCommand 和 checksRequired。配置错误会立即提示，避免后续难以排查的问题。

与 GitHub 合并队列的比较

GitHub 的合并队列仅适用于 Enterprise Cloud 用户，且每次着陆都会消耗 Actions 分钟数。而 Claude Code 合并队列则在本地运行，免费使用，不要求创建拉取请求。

命令列表

工具提供了多个命令：claude-code-merge-queue hook worktree-create 用于创建工作目录；build-lock 用于串行化构建；land 用于通过 FIFO 队列将分支推送到集成分支；sync 用于同步主分支；promote 用于将集成分支推送到生产环境（仅限人类操作）；preview 用于实时查看分支的工作树；port 打印开发服务器端口；prune 清理已着陆的分支分支。此外，预推送钩子强制执行 land 命令，并确保 checkCommand 通过。

初始化

运行 init 命令会生成配置文件、更新 CLAUDE.md、配置工作目录钩子、设置 Husky 钩子，并添加 npm 脚本。同时生成一个预检脚本，用于在着陆前检查分支状态。

紧急出口

当推送被阻止时，可以通过设置环境变量 CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 来绕过保护。这是一个约定而非硬性保证，主要防止意外错误。

局限性

该工具没有人工审查环节，checkCommand 是唯一的门控。锁机制基于 PID 存活状态，而非超时，因此 kill -9 后会自动回收。目前仅支持单机运行，不支持集群。它不是一个安全边界，只能防止意外而非恶意操作。如果 checkCommand 运行时间较长，吞吐量会受限（例如 3-4 分钟的测试套件导致每小时少于 20 次着陆）。如果发生合并冲突，工具会自动中止并提示代理解决。

许可

项目采用 MIT 许可证，允许自由使用、修改和分发。