funador/claude-code-merge-queue — 为并行运行的 Claude Code 智能体提供本地化合并队列，解决多智能体协作时的代码冲突与顺序控制问题。

一、背景与痛点

随着 AI 辅助编程工具（如 Claude Code、GitHub Copilot、Cursor 等）的普及，开发者开始尝试让多个 AI 智能体同时处理不同模块的代码任务。然而，当多个智能体并行修改同一代码库时，会引发几个棘手问题：

• 并发冲突：两个智能体同时修改同一文件的不同部分，或先后修改相同行，导致合并时产生大量冲突。
• 顺序依赖：某些任务需要按特定顺序执行（如先重构接口，再修改调用方），但并行智能体无法感知彼此的进度。
• 状态混乱：每个智能体都基于最新的 main 分支工作，但一旦其中一个合并完成，其他智能体的基础分支就过时了，需要频繁 rebase。
• 人工干预成本高：传统做法是手动协调智能体的工作流，或者依赖 CI/CD 的合并按钮，但这样会打断 AI 的自动化流程。

claude-code-merge-queue 正是为解决这些痛点而生。它本质上是一个本地运行的合并队列守护进程，专门为 Claude Code 智能体（或其他 CLI 工具）设计，允许你以串行化、可控的方式将多个并行分支的修改安全地合并到主分支。

二、快速上手

安装

确保你的系统已安装 Node.js（≥18）和 Git。通过 npm 全局安装：

bash
npm install -g claude-code-merge-queue

或者使用 npx 直接运行（推荐用于 CI/CD 场景）：

bash
npx claude-code-merge-queue

基本用法

假设你有两个 Claude Code 智能体分别在 feature/agent-a 和 feature/agent-b 分支上工作。你想让它们按顺序合并到 main。

1. 启动合并队列守护进程：

bash
merge-queue start --base main --queue-dir .merge-queue

参数说明：

• --base：目标分支（通常是 main 或 master）
• --queue-dir：队列状态存储目录（可选，默认 .merge-queue）

2. 将分支提交到队列：

bash
merge-queue enqueue feature/agent-a
merge-queue enqueue feature/agent-b

3. 查看队列状态：

bash
merge-queue status

输出示例：

Queue: [feature/agent-a (waiting), feature/agent-b (waiting)]
Currently merging: none

4. 自动触发合并：守护进程会按 FIFO 顺序依次处理队列中的分支。当第一个分支合并成功后，自动开始处理下一个。

与 Claude Code 集成

你可以在 Claude Code 的配置文件中（如 .claude.yml）添加钩子，让智能体在完成任务后自动执行 merge-queue enqueue。例如：

yaml

.claude.yml

hooks:
after_task:
- command: "merge-queue enqueue $BRANCH_NAME"
run: always

这样，每个智能体完成代码修改后，会自动将当前分支加入合并队列，等待前面任务完成后安全合并。

三、核心亮点

1. 轻量级、零依赖

项目本身仅依赖 Node.js 原生模块和 Git CLI，没有引入复杂的消息队列（如 RabbitMQ、Kafka）或外部数据库。所有状态存储在本地文件系统中，启动和运行开销极低。

2. 智能冲突检测与重试

当队列中的一个分支合并失败（例如因为冲突），守护进程会：

• 自动中止当前合并，将分支标记为 failed
• 保留失败分支的合并冲突状态，方便人工排查
• 继续处理队列中的下一个分支（不会阻塞整个队列）
• 提供 retry 命令，允许在修复冲突后重新入队

3. 支持自定义合并策略

你可以通过 --merge-strategy 参数指定合并方式：

• merge：创建合并提交（默认）
• rebase：变基后快进合并
• squash：压缩为一个提交

例如：
bash
merge-queue start --merge-strategy rebase

4. 并发控制与超时保护

通过 --max-concurrent 参数可以控制同时合并的分支数量（默认为 1，即严格串行）。此外，--timeout 参数设置每个合并操作的最大执行时间（单位秒），防止某个分支长时间卡住。

5. 完整的 CLI 工具链

除了 start、enqueue、status，还提供：

• dequeue：从队列中移除指定分支
• pause / resume：暂停/恢复队列处理
• reset：清空队列并重置状态
• log：查看历史合并日志

四、适用场景

场景 1：多智能体并行开发

假设你有一个大型代码库，需要同时重构 API 层、更新前端组件、编写文档。你可以启动三个独立的 Claude Code 会话，每个负责一个模块，并让它们将修改推送到不同分支。合并队列确保这些分支按合理顺序合并，避免相互覆盖。

场景 2：AI 驱动的自动化代码审查与修复

在 CI/CD 流水线中，你可以让 Claude Code 自动分析代码质量并生成修复分支。合并队列可以将这些修复分支串行合并，防止修复互相冲突。

场景 3：教学与演示

在直播或教程中演示 AI 编程时，合并队列可以让你优雅地展示多个智能体协作的实际效果，而不必担心合并失败带来的尴尬。

五、与其他方案的对比

特性	claude-code-merge-queue	GitHub Merge Queue	手动 Git 工作流
运行位置	本地/CI	云端（GitHub 服务器）	本地
依赖	仅 Node.js + Git	需要 GitHub 企业版或付费计划	无
冲突处理	自动检测 + 重试	自动检测 + 重试	手动解决
并发控制	可配置（默认串行）	串行	无内置支持
与 AI 集成	原生支持 Claude Code 钩子	需通过 GitHub Actions 间接集成	需手动脚本
成本	免费开源	付费（企业版）	免费
灵活性	高（自定义策略、超时等）	中（受限于 GitHub 功能）	低（全靠人工）

优势：

• 免费且可本地化运行，不依赖第三方云服务。
• 专为 AI 智能体场景设计，集成简单。
• 轻量级，适合小型团队或个人项目。

劣势：

• 不支持跨仓库合并（仅限单仓库）。
• 没有 Web UI 界面，仅提供 CLI。
• 对于超大规模团队（数百个分支同时排队），性能可能不如企业级方案。

六、深入技术细节

工作流程

1. 守护进程启动后，在 --queue-dir 目录下创建一个 JSON 文件 queue.json，记录队列状态。
2. 当执行 enqueue 时，工具会验证分支是否存在、是否与 base 分支有共同祖先，然后将分支信息追加到队列尾部。
3. 守护进程轮询（每秒一次）检查队列头部是否有待处理分支。
4. 对于待处理分支，执行 git checkout base → git merge <branch>（或按策略执行 rebase/squash）。
5. 合并成功后，删除分支引用（可选，通过 --delete-after-merge 参数控制），并记录日志。
6. 合并失败时，保留分支，标记状态为 failed，并输出冲突文件列表。

冲突处理机制

当 git merge 返回非零退出码时，工具会解析 git status 输出，提取冲突文件列表，并存储到 failed_merge_<branch>.json 中。你可以使用 merge-queue retry <branch> 命令重新尝试合并（前提是你已经手动解决了冲突）。

安全性考量

• 所有操作都在本地 Git 仓库中执行，不会向外部发送任何数据。
• 通过文件锁（lockfile）防止多个 enqueue 或 dequeue 操作同时修改队列状态。
• 支持 --dry-run 模式，只模拟操作而不实际执行合并。

七、未来展望

项目目前处于早期阶段（Stars 295），但设计思路清晰。未来可能的发展方向包括：

• 支持 Webhook 通知（如 Slack、Discord）
• 提供可视化仪表板
• 支持更复杂的依赖关系（如 DAG 形式的合并顺序）
• 与更多 AI 编程工具（如 Cursor、Copilot）集成

八、总结

claude-code-merge-queue 是一个小而美的工具，精准解决了 AI 辅助编程中一个真实且日益突出的痛点。它不追求大而全，而是聚焦于“本地化、轻量级、易集成”的合并队列实现。对于正在探索多智能体协作编程的开发者，或者希望自动化代码合并流程的团队，这是一个值得一试的开源项目。

项目链接：https://github.com/funador/claude-code-merge-queue