claude-code-merge-queue：用于并行 AI 代理的本地合并队列

claude-code-merge-queue 是一个零成本的本地合并队列，通过对并行 Claude Code 代理的落地、构建和测试进行序列化，防止推送竞争和冗余构建。

claude-code-merge-queue：用于并行 AI 代理的本地合并队列

并行 AI 代理的本地序列化

claude-code-merge-queue 是一个本地的、零成本的合并队列，旨在管理在同一代码库上工作的多个并行 Claude Code 代理。它通过对落地、构建和测试代码更改的过程进行序列化，防止常见的并发问题——例如推送竞争、冗余的繁重构建以及共享资源的测试不稳定性。

不同于基于云的合并队列，该工具完全在开发者的本地机器上运行，省去了为每次队列尝试购买企业计划或 GitHub Actions 分钟的需求。

核心功能与命令

该工具直接集成 Claude Code 的原生工作树创建，并提供一套命令来管理由代理驱动的更改生命周期：

落地与同步

• land：通过先进先出（FIFO）队列对一个分支进行 rebase 并推送到集成分支。这确保两个代理永远不会同时尝试推送。
• sync：快进主检出以反映最新的已落地更改，如果 lockfile 已更改则重新安装依赖。
• promote：仅供人工使用的命令，用于将集成分支发布到生产环境。此命令在代理指令中被明确排除，以防止自动化的生产部署。

开发与维护

• build-lock：在机器上对所有分支序列化运行指定的构建命令，以防止资源争用。
• preview：将分支的实时工作树（包括未提交的更改）镜像到主检出，以便立即进行人工检查，无需完整构建。
• port：根据目录名计算并打印特定分支的开发服务器端口。
• prune：清理已落地分支的工作树。

技术实现与防护措施

配置与设置

通过 npx claude-code-merge-queue init 进行初始化，会创建 claude-code-merge-queue.config.mjs 文件并更新 CLAUDE.md，指示代理在测试通过后自行落地工作。它还在 .claude/settings.json 中加入 WorktreeCreate 钩子，并设置 pre-push 钩子（如果有 Husky）以确保在受保护分支上使用 land 而不是直接 git push。

安全机制

• 紧急开关：要绕过受保护分支的阻止，用户可以在 git push 时使用环境变量 CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1。这是一种基于约定的防护措施，而非安全边界。
• 崩溃安全锁：锁通过 PID 存活状态管理。如果进程被杀死（例如 kill -9），下一个进程会检测到死亡的 PID 并重新获取锁，从而无需超时机制。
• 冲突处理：如果在 land 过程中出现 rebase 冲突，工具会执行 git rebase --abort 并保持工作树干净。随后代理会通过 CLAUDE.md 被指示解决冲突并重新运行该命令。

对比：本地 vs. 云合并队列

功能	GitHub 合并队列	Claude Code 合并队列
私有仓库支持	仅企业云	任意计划，任意仓库
成本	每次尝试的 GitHub Actions 分钟	$0（本地执行）
要求	需要 Pull Request	直接 rebase + push

约束与限制

• 缺乏人工审查：checkCommand（例如 npm run check）是唯一的门槛。如果该命令通过，代码即落地。没有内置的人工批准机制。
• 单机范围：FIFO 队列存储在本地临时存储中。如果多台机器同时尝试落地更改，会遇到标准的 Git 非快进拒绝。
• 吞吐上限：每小时的落地次数受 checkCommand 时长限制。例如，4 分钟的测试套件会将吞吐量限制在每小时不到 20 次落地。
• 安全性：该工具不是安全边界；拥有 shell 访问权限的用户仍可使用 git push --no-verify 绕过钩子。

社区观点

社区用户提出了管理代理并发的替代方案，例如使用 jj（Jujutsu）代替 Git 更灵活地处理工作树和分支，或实现使用基于内容的摘要来跳过冗余测试的自定义部署系统。一些开发者指出，对于小规模操作，针对每次对话的独立工作树结合调度代理即可在无需专用合并队列工具的情况下实现类似效果。