claude-code-merge-queue 是一个面向 Claude Code 多代理并行开发场景的本地合并队列工具。它利用 Claude Code 的 worktree 隔离能力，为多个并行 agent 提供串行化的 build、test、rebase、push 流程，避免多个 agent 同时向同一分支落地代码时产生冲突、重复 rebase、资源竞争或测试互相污染。项目使用 TypeScript 编写，Node.js >= 18，MIT 协议，运行时依赖为 0。
适用领域
AI 编程助手工作流 / Claude Code 自动化 / Git 工作流 / 本地 Merge Queue / 多 agent 并行开发 / CI/CD 前置检查 / 开发者工具 / 测试资源隔离
配置难度
中等。基础安装和初始化较简单，但要在真实团队或复杂项目中稳定使用，需要理解 Git worktree、pre-push hook、分支保护策略、测试门禁、Claude Code agent 行为以及共享测试资源隔离。对熟悉 Git 和 Node.js 工具链的开发者较友好。
商业价值
对于重度使用 Claude Code 的团队，该工具可以显著提升多 agent 并行开发的可控性，减少 push 冲突、重复 rebase、本地资源争抢和假性 flaky test，从而提高 AI 编程流水线吞吐。它以本地方式提供类似 merge queue 的能力，降低 GitHub Enterprise 或云端 CI 队列成本。商业价值主要体现在提升 AI 辅助开发效率、减少人工协调成本、让自动化测试成为稳定门禁，以及为小团队提供低成本的多代理协作基础设施。
01
技术亮点
- 专门解决 Claude Code 多 agent 并行开发后的落地冲突问题。
- 本地零成本 merge queue，不依赖 GitHub Enterprise Merge Queue，也不消耗 GitHub Actions minutes。
- 通过 FIFO 队列串行化 land、build、test、push，降低并发冲突和资源争用。
- init 命令自动完成大部分设置，包括配置文件、CLAUDE.md、Claude hook、package scripts、preflight 脚本等。
- 通过 pre-push hook 阻止直接 push 到 integration branch、productionBranch 或 protectedBranches。
- 默认要求 checkCommand 通过后才能落地，避免未验证代码进入 integration branch。
- 支持 build-lock，将重型构建命令在多 lane 间串行执行。
- 支持 preview，将 lane 的工作树内容即时映射到主 checkout，方便快速查看效果。
- 支持 sync，在落地后快进主 checkout，并在 lockfile 变化时重新安装依赖。
- 锁机制基于 PID liveness 判断失效状态，而不是依赖固定超时，具备较好的 crash-safe 设计。
- MIT 协议，运行时依赖为 0，适合纳入开发工具链。
02
目标用户
- 使用 Claude Code 进行多 agent 并行开发的个人开发者
- 希望让多个 Claude Code session 同时改代码的团队
- 不想为 GitHub Merge Queue 或 GitHub Actions 队列成本付费的小团队
- 需要在本地串行化构建、测试、推送流程的开发者
- 愿意采用自动化测试作为主要代码质量门禁的团队
- 使用 Git worktree 管理多条开发 lane 的高级开发者
03
配置要求
- 需要 Node.js >= 18。
- 需要 Git 仓库，并且推荐使用 Claude Code 的 --worktree 能力。
- 需要配置 claude-code-merge-queue.config.mjs。
- integrationBranch 必须设置，例如 main，用作 agent 落地代码的目标分支。
- checkCommand 强烈建议设置，例如 npm run check；如果 checksRequired 为 true 且没有 checkCommand，push 会被阻止。
- 可选配置 productionBranch，用于 integration branch 与生产分支分离的两阶段发布模型。
- 可配置 branchPrefix、worktreeSuffix、portBase、protectedBranches、symlinks、buildOutputDirs、regenerableFiles 等参数。
- 如果使用 Husky，init 会创建或追加 .husky/pre-push；如果未使用 Husky，它不会静默写入未被团队共享的 .git/hooks/pre-push。
- 如果测试依赖共享资源，需要根据项目情况扩展 ephemeral resource 逻辑，避免并发测试污染数据库、队列或临时目录。
04
适用场景
- 多个 Claude Code agent 同时在不同 worktree 中开发，最终按 FIFO 顺序落到同一个 integration branch
- 防止多个 agent 同时执行重型 build/test 导致本机资源耗尽
- 避免多个测试进程同时操作共享数据库、队列或临时资源造成假性 flaky test
- 在本地模拟类似 GitHub Merge Queue 的串行合并流程，但不依赖 GitHub Enterprise 或 GitHub Actions minutes
- 自动阻止 agent 或开发者直接 push 到受保护分支，强制通过 land 流程
- 在不真正构建的情况下，将某个 lane 的工作区内容预览到主 checkout
- 在 integration branch 验证稳定后，由人类手动 promote 到 production branch
05
部署与配置
- 确保本机已安装 Node.js 18 或更高版本。
- 在目标仓库中安装开发依赖：npm install --save-dev claude-code-merge-queue。也可以使用 pnpm add -D、yarn add -D 或 bun add -d。
- 运行初始化命令：npx claude-code-merge-queue init。
- 检查并提交 init 生成或修改的文件，包括 claude-code-merge-queue.config.mjs、CLAUDE.md、.claude/settings.json、package.json scripts、preflight 脚本，以及可能修改的 .husky/pre-push。
- 确认 package.json 中存在可用于落地前检查的脚本，例如 check、check:push、ci 或 test；如果自动检测失败，需要手动设置 checkCommand。
- 使用 claude --worktree <name> 创建隔离开发 lane，后续 agent 可根据 CLAUDE.md 指令自动 land。
- 需要发布时，由人类执行 claude-code-merge-queue promote。
06
风险与注意事项
- 只协调单台机器上的队列，无法跨多台开发机全局串行化；多台机器同时 push 仍会回到 Git 的非 fast-forward 冲突处理。
- 不是安全边界。拥有 shell 权限的 agent 或用户可以通过 --no-verify、删除 hook、修改配置或设置紧急环境变量绕过限制。
- 质量保障完全依赖 checkCommand。如果 checkCommand 覆盖不足或只是 echo ok，工具无法保证代码质量。
- 不适合需要人工 review 每个变更后才能合并的团队；该项目的理念是测试作为 reviewer，人类只负责发布决策。
- 如果 checkCommand 很慢，FIFO 队列会成为吞吐瓶颈，因为一次只能有一个 lane 完成落地检查。
- Claude Code WorktreeCreate hook 是相对较新的能力，如果 Claude Code 行为变化，相关自动化可能需要调整。
- 对于复杂 monorepo、非 Node 项目或自定义构建系统，自动检测 checkCommand 和默认配置可能需要手工适配。
- 如果测试使用共享数据库、消息队列或缓存，而没有配置隔离资源，仍可能出现并发污染。
2026-07-07
第23名
新收录 · github_search
