Claude Code 本地合并队列：一个用于并行 Claude Code 代理的本地合并队列工具，解决多 AI 代理协作时的代码冲突与合并难题。

---

一、项目背景与痛点分析

随着大语言模型（LLM）在代码生成领域的爆发式增长，以 Claude Code 为代表的 AI 编程代理（Agent）已经能够独立完成从需求理解到代码提交的完整开发任务。然而，当多个 Claude Code 代理被同时派发到同一个代码仓库工作时，一个经典的分布式系统问题便浮出水面：并行写入冲突。

传统开发流程中，人类开发者通过 Git 分支管理、代码审查和合并队列（如 GitHub 的 Merge Queue）来协调并行工作。但 AI 代理的运行速度远快于人类，且缺乏人类在冲突解决中的上下文感知能力。如果不加控制地让多个 Claude Code 代理同时修改同一仓库，很容易出现：

• 直接覆盖彼此的更改
• 产生难以自动解决的复杂冲突
• 丢失未提交的阶段性成果
• 频繁触发 CI/CD 重跑，浪费算力和时间

funador/claude-code-merge-queue 正是为了解决这个痛点而生。它提供了一个轻量级的本地合并队列，让多个并行运行的 Claude Code 代理能够安全、有序地共享同一个工作目录，而不会相互踩踏。

---

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

2.1 环境准备

• Node.js >= 18
• npm 或 yarn
• 已安装并配置好 Claude Code CLI

2.2 安装

bash

全局安装（推荐）

npm install -g claude-code-merge-queue

或使用 npx 直接运行

npx claude-code-merge-queue

2.3 基本使用

项目本身是一个 CLI 工具，核心概念是：启动一个队列服务器，多个 Claude Code 代理通过它来串行化对工作目录的修改。

第一步：启动队列服务器

在项目根目录下运行：

bash
claude-code-merge-queue start

默认会在本地 3000 端口启动一个 HTTP 服务。你也可以指定端口：

bash
claude-code-merge-queue start --port 8080

第二步：让 Claude Code 代理通过队列工作

你可以在多个终端窗口中分别运行不同的 Claude Code 任务，每个任务都通过 --queue 参数连接到队列：

bash

终端 1：实现用户登录功能

claude --queue http://localhost:3000 "请实现用户登录功能，包括 JWT 认证"

终端 2：添加数据库迁移脚本

claude --queue http://localhost:3000 "添加用户表的数据库迁移脚本"

终端 3：修复已知 bug

claude --queue http://localhost:3000 "修复 issues/42 中描述的空指针异常"

每个 Claude Code 代理在修改代码前，会先向队列请求锁。只有获得锁的代理才能执行写入操作，其它代理会等待当前操作完成后自动获取锁并继续。

2.4 高级用法：自定义配置

创建 merge-queue.config.json 配置文件：

{
"port": 3000,
"timeout": 600000,
"maxRetries": 3,
"conflictStrategy": "auto-merge",
"backupEnabled": true,
"backupDir": ".merge-queue-backups"
}

• timeout：单个代理持有锁的最大时间（毫秒），防止死锁
• maxRetries：获取锁失败时的重试次数
• conflictStrategy：冲突解决策略，支持 auto-merge（自动合并）、fail-fast（快速失败）、manual（手动干预）
• backupEnabled：是否在每次合并前创建备份

---

三、核心亮点与技术实现

3.1 基于令牌桶的公平调度

与简单的互斥锁不同，该项目实现了类似令牌桶（Token Bucket）的调度算法。每个代理在启动时获得一个初始令牌，令牌会根据任务复杂度动态消耗和恢复。这确保了：

• 短任务不会被长任务无限阻塞
• 高优先级任务可以插队（通过 --priority 参数）
• 避免单个代理长期霸占队列

3.2 智能冲突预检测

在代理实际写入文件之前，队列服务会执行一个预合并检查：

1. 获取当前工作目录的快照
2. 模拟应用代理将要做的更改
3. 如果检测到冲突，立即通知代理并给出冲突文件列表
4. 代理可以根据反馈调整其修改范围

这比等到 Git 合并时才发现冲突要高效得多。

3.3 零侵入设计

项目不需要修改 Claude Code 本身的代码，也不需要额外的插件。它通过包装 claude CLI 命令，在标准输入/输出流层面进行拦截和控制。这意味着：

• 兼容所有 Claude Code 版本
• 不改变 Claude Code 的行为逻辑
• 可以随时启用/禁用，不影响正常开发流程

3.4 自动备份与回滚

每次代理完成一个操作单元后，队列会自动创建一个 Git 提交（或存档快照）。如果后续操作导致问题，可以轻松回滚到任意历史状态。这在调试 AI 产生的不良修改时尤其有用。

3.5 可观测性

内置一个简单的 Web 仪表盘（默认在 http://localhost:3000/dashboard），展示：

• 当前队列状态（等待中、运行中、已完成）
• 每个代理的任务描述和耗时
• 冲突发生频率和解决方式
• 历史操作记录

---

四、适用场景

4.1 大规模 AI 辅助重构

当需要对整个代码库进行大规模重构（如迁移框架、重命名 API、统一错误处理）时，可以同时派出多个 Claude Code 代理分别处理不同模块，队列确保它们不会互相干扰。

4.2 自动化代码审查与修复

集成到 CI/CD 流水线中：当代码扫描工具发现多个问题时，可以并行启动多个 Claude Code 代理分别修复，然后通过合并队列安全地合并回主分支。

4.3 多人 AI 辅助协作

团队中多个开发者同时使用 Claude Code 辅助编程时，队列避免了“你改了我刚改的文件”这种尴尬情况。

4.4 教学与演示

在编程教学场景中，可以同时让多个 Claude Code 代理演示不同的实现方案，队列保证每个方案都在干净的代码基础上进行。

---

五、同类项目对比

特性	claude-code-merge-queue	GitHub Merge Queue	Git 分支策略	自建锁服务
定位	本地开发时的实时协作	远程 PR 合并管理	代码管理基础	通用分布式锁
与 AI 代理集成	原生支持，零配置	不直接支持	需手动脚本	需二次开发
冲突检测时机	写入前预检测	PR 合并时	合并时	自定义
部署复杂度	单命令启动	云端服务	内置功能	需搭建 Redis 等
回滚能力	内置自动备份	需手动 revert	需手动 revert	需自行实现
对 Claude Code 友好度	★★★★★	★☆☆☆☆	★★☆☆☆	★★☆☆☆

优势总结：

• 相比 GitHub Merge Queue，它专注于本地开发阶段的实时协作，而不是远程 PR 的合并
• 相比传统 Git 分支策略，它提供了自动化的锁管理和冲突预检测，减少了人工干预
• 相比自建锁服务（如 Redis 分布式锁），它开箱即用，且专门为 Claude Code 优化了接口

不足之处：

• 目前仅支持 Claude Code，不支持其他 AI 编程代理（如 GitHub Copilot Chat 等）
• 项目仍处于早期阶段（Stars 276），社区贡献和文档尚不完善
• 没有提供图形化的冲突解决界面，冲突仍需在终端中处理

---

六、技术架构简析

项目使用 TypeScript 编写，核心架构如下：

┌─────────────────────────────────────────────┐
│ Queue Server │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Scheduler│ │ Lock │ │ Conflict │ │
│ │ (令牌桶) │ │ Manager │ │ Detector │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Backup │ │ History │ │ Dashboard│ │
│ │ Manager │ │ Recorder │ │ (Web) │ │
│ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────┘
▲ HTTP/WebSocket │
│ │
┌────────┴────────┐ ┌──────────────────────┘
│ Claude Code Agent 1│ │ Claude Code Agent 2
└─────────────────────┘ └──────────────────────

• Scheduler：基于令牌桶的调度算法，决定哪个代理获得执行权
• Lock Manager：管理文件级锁，支持读写锁（多个代理可同时读取，但写入互斥）
• Conflict Detector：使用类似 Git 的三路合并算法进行预检测
• Backup Manager：在每次写入前创建快照，支持快速回滚
• Dashboard：基于 Express 的轻量级 Web 界面

---

七、总结与展望

funador/claude-code-merge-queue 是一个定位精准、设计巧妙的小工具。它没有试图解决所有分布式协作问题，而是专注于一个非常具体的场景：让多个 Claude Code 代理能够在同一个本地仓库中高效、安全地并行工作。

对于已经在日常开发中重度使用 Claude Code 的团队或个人来说，这个工具可以显著提升工作效率，减少因并行操作导致的代码冲突和调试时间。它的零侵入设计、自动备份和智能调度算法，都体现了作者对实际开发痛点的深刻理解。

值得改进的方向：

1. 支持更多 AI 编程代理（如 Copilot、Cursor 等）
2. 提供更友好的冲突可视化解决界面
3. 增加远程队列模式，支持分布式团队
4. 与主流 IDE 集成，提供更无缝的体验

尽管如此，作为一个仅有 276 Stars 的开源项目，它已经展现出了极高的实用价值和工程水准。如果你正在探索如何规模化使用 AI 编程代理，这个项目值得一试。

---

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