funador/claude-code-merge-queue 是一个为并行运行的 Claude Code 代理提供本地合并队列的工具，实现多AI代理安全、有序地协同编辑同一代码仓库。

一、项目背景与痛点

随着大语言模型（LLM）在代码生成领域的爆发，开发者开始使用 Claude Code、Cursor 等AI编程助手来加速开发。然而，当多个 Claude Code 代理同时操作同一个代码仓库时，问题随之而来：

• 文件冲突：两个代理同时修改同一个文件，后写入的内容可能覆盖先前的修改。
• 逻辑矛盾：一个代理修复了A模块的bug，另一个代理在不知情的情况下在B模块中引入依赖A模块的代码，导致集成失败。
• 状态混乱：没有统一的工作流管理，每个代理各自为政，最终合并时冲突频发。

传统的解决方式是让开发者手动协调，或者使用 Git 分支+PR机制，但这对于AI代理来说过于沉重——代理不像人类那样能理解复杂的Git操作和冲突解决。

claude-code-merge-queue 正是为了解决这个痛点而生：它提供了一个轻量的本地合并队列，让多个 Claude Code 代理能够像团队中的开发者一样，通过队列机制有序地提交、合并代码变更，避免冲突，保证代码库的一致性。

二、快速上手：安装与使用

安装

项目基于 Node.js（TypeScript），安装非常简单：

bash

通过 npm 全局安装

npm install -g claude-code-merge-queue

或者从源码安装

git clone https://github.com/funador/claude-code-merge-queue.git
cd claude-code-merge-queue
npm install
npm run build

基本使用

假设你有一个项目目录，希望让两个 Claude Code 代理并行工作：

1. 启动合并队列服务

bash

在项目根目录启动队列服务

merge-queue start

2. 在每个代理的工作目录中初始化队列客户端

bash

代理A的工作目录

cd /path/to/project/agent-a
merge-queue init --queue-url http://localhost:3000

代理B的工作目录

cd /path/to/project/agent-b
merge-queue init --queue-url http://localhost:3000

3. 代理在完成修改后提交合并请求

python

假设你在Claude Code的脚本中调用

import subprocess

代理完成修改后

subprocess.run(["merge-queue", "submit", "--message", "修复了登录模块的XSS漏洞"])

4. 队列自动处理合并

队列服务会按顺序处理提交的变更：

• 检查当前是否有其他变更正在合并
• 如果没有，立即执行 git merge 或 git apply
• 如果有，将变更放入FIFO队列，等待前面的变更完成
• 合并成功或失败都会通知代理（通过回调或日志）

高级用法：多代理并行脚本示例

下面是一个更完整的示例，展示如何让两个Claude Code代理并行工作并安全合并：

代理A（前端模块）
bash
#!/bin/bash

agent-a.sh

cd /workspace/project/agent-a
merge-queue init --queue-url http://localhost:3000 --agent-name "agent-a"

让Claude Code修改前端代码

claude code -p "在src/components/Header.tsx中添加一个用户头像组件"

提交变更

merge-queue submit --message "添加用户头像组件"

代理B（后端模块）
bash
#!/bin/bash

agent-b.sh

cd /workspace/project/agent-b
merge-queue init --queue-url http://localhost:3000 --agent-name "agent-b"

让Claude Code修改后端API

claude code -p "在src/api/user.ts中添加获取用户头像的API端点"

提交变更

merge-queue submit --message "添加用户头像API"

启动队列并运行两个代理
bash

终端1：启动队列

merge-queue start --port 3000

终端2和3：分别运行代理

bash agent-a.sh &
bash agent-b.sh &

队列服务会自动保证：代理A和代理B的修改不会相互覆盖，即使它们修改了同一个文件的不同部分，也会尝试自动合并。

三、核心亮点深度解析

1. 轻量级本地合并队列

与GitHub的合并队列（如 Merge Queue for GitHub）不同，这个项目完全在本地运行，不依赖任何云服务。它使用文件系统锁和内存队列来实现简单的FIFO调度，无需安装数据库或消息中间件。

2. 智能冲突检测与自动合并

当多个代理的修改涉及同一个文件时，队列会尝试使用 Git 的自动合并机制。如果自动合并失败（例如同一行被两个代理修改），队列会：

• 将冲突信息写入日志
• 暂停后续合并
• 等待人工干预或代理重新提交

3. 与Claude Code原生集成

项目设计时充分考虑了Claude Code的工作模式。Claude Code 通常以“会话”为单位进行修改，每个会话可能修改多个文件。merge-queue 支持以会话粒度提交变更，而不是每次文件保存都触发合并，减少了不必要的冲突。

4. 可配置的合并策略

用户可以通过配置文件或环境变量设置合并策略：

• strict：严格顺序执行，前一个合并完成后才能提交下一个
• optimistic：尝试并行合并，仅当检测到冲突时才回退到顺序模式
• manual：仅收集变更，由开发者手动触发合并

5. 详细的日志与审计

所有合并操作都会记录详细的日志，包括：

• 每个代理提交的变更内容（diff）
• 合并开始和结束时间
• 合并结果（成功/失败/冲突）
• 冲突的具体位置

这对于调试AI代理的行为非常有帮助。

四、适用场景

场景1：大规模代码重构

当你需要同时重构多个模块时，可以启动多个Claude Code代理，每个负责一个模块。合并队列确保重构后的代码能够平滑集成。

场景2：自动化测试与修复

假设你有一个自动化流程：

1. 运行测试套件
2. 将失败的测试用例发送给Claude Code代理进行修复
3. 多个代理并行修复不同的失败用例
4. 通过合并队列将修复代码安全合并回主分支

场景3：代码审查辅助

在代码审查过程中，你可以让Claude Code代理根据审查意见生成修改建议，然后通过合并队列提交。审查者可以逐个审查合并请求，而不是一次性面对大量修改。

场景4：持续集成流水线

将合并队列集成到CI/CD流水线中，让多个AI代理在隔离环境中并行生成代码，然后通过队列合并到测试分支进行集成测试。

五、同类项目对比

特性	claude-code-merge-queue	GitHub Merge Queue	GitLab Merge Train	自定义Git工作流
部署方式	本地轻量级服务	GitHub托管	GitLab托管	需自行搭建
AI代理友好	✅ 专为AI代理设计	❌ 面向人类PR	❌ 面向人类PR	需自行适配
冲突处理	自动合并+冲突回退	自动合并+PR回退	自动合并+回退	需手动解决
并行度	支持并行提交	串行合并	串行合并	取决于实现
依赖	仅Node.js	GitHub账号	GitLab账号	Git+CI工具
成本	免费	免费/付费（取决于计划）	免费/付费	取决于基础设施
学习曲线	低（3个命令）	中（需理解GitHub Actions）	中	高

结论：如果你的场景是让多个Claude Code代理并行工作，claude-code-merge-queue 是目前最直接的解决方案。它比GitHub/GitLab的合并队列更轻量、更专注于AI代理场景；比自定义Git工作流更容易上手。

六、技术架构简析

项目核心架构如下：

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Claude Code A │ │ Claude Code B │ │ Claude Code C │
│ (客户端) │ │ (客户端) │ │ (客户端) │
└────────┬────────┘ └────────┬────────┘ └────────┬────────┘
│ │ │
│ submit │ submit │ submit
▼ ▼ ▼
┌──────────────────────────────────────────────────────────────────┐
│ Merge Queue Server (HTTP) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 队列缓冲区 │→│ 合并执行器 │→│ Git操作器 │ │
│ │ (FIFO) │ │ (单线程) │ │ (git apply) │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ 文件锁管理器 │ │
│ │ (避免并发写) │ │
│ └──────────────────┘ │
└──────────────────────────────────────────────────────────────────┘
│
▼
┌──────────────────┐
│ Git仓库 │
│ (工作目录) │
└──────────────────┘

• 客户端：通过HTTP API向队列服务提交变更（可以是文件路径列表或git diff）
• 队列服务：维护一个FIFO队列，使用文件锁防止并发写操作
• 合并执行器：调用 git apply 或 git merge 执行实际合并
• Git操作器：处理与Git仓库的交互，包括冲突检测和回滚

七、局限性与发展方向

当前局限

1. 仅支持本地Git仓库：不能直接用于远程仓库的协作（如GitHub上的多个fork）
2. 无图形界面：只有命令行工具，对非技术用户不友好
3. 冲突解决依赖人工：自动合并失败时，需要人工介入，没有提供AI辅助的冲突解决策略
4. 性能瓶颈：单线程合并执行器在大量小变更场景下可能成为瓶颈

未来展望

• 支持远程Git仓库（通过SSH或HTTPS）
• 集成AI冲突解决（利用Claude Code本身来解决合并冲突）
• 提供Web仪表盘，可视化队列状态和合并历史
• 支持插件系统，允许自定义合并策略和通知方式

八、总结

claude-code-merge-queue 是一个小而精的工具，它解决了一个非常具体但日益重要的问题：如何让多个AI编程代理安全地并行工作。在AI辅助编程快速普及的今天，这类工具将成为开发工作流中不可或缺的一环。

如果你正在使用Claude Code进行大规模代码生成或重构，或者你想探索“AI团队协作”的编程模式，这个项目值得一试。它安装简单、使用直观，能够立刻提升多代理协作的安全性和效率。

项目地址：https://github.com/funador/claude-code-merge-queue