Show HN: 为并行Claude Code代理设计的本地合并队列
摘要
Claude Code Merge Queue 是一个本地、零成本的合并队列,可将并行Claude Code代理的落地操作序列化,以避免推送冲突和构建冲突。它提供了用于管理并行代理工作流的CLI工具和配置。
我每天通过4-5个并行代理在MacBook Air上推送多达90次提交。可以想象,当所有代理尝试在一台8GB内存的机器上构建、测试和运行开发服务器时,这简直就是通往强制退出和重启的快车道。我也不想每天为90次推送支付CI分钟费用。<p>因此,我设计了一个本地合并队列,使所有提交依次落地并经过充分测试。希望这对使用配置较低机器的其他人有所帮助。欢迎任何反馈。
查看缓存全文
缓存时间: 2026/07/30 01:46
funador/claude-code-merge-queue Source: https://github.com/funador/claude-code-merge-queue # Claude Code Merge Queue 🚦 本地、零成本的合并队列,用于并行运行 Claude Code 代理。 多个代理同时落地、构建和测试——此工具将其序列化,避免推送冲突、重复的重构建以及共享资源导致的测试不稳定。 ## ⚡ 快速入门 bash npm install --save-dev claude-code-merge-queue # 或者:pnpm add -D / yarn add -D / bun add -d npx claude-code-merge-queue init ## 目录 - ⚙️ 配置 - 🆚 对比 GitHub 的合并队列 - 🧰 内含工具 - 🚨 紧急逃生口 - 🔍 已知限制 - 📄 许可证 ## ⚙️ 配置 所有配置集中在一个文件中——详见 examples/claude-code-merge-queue.config.mjs,每个字段都有注释。简要版本: js export default { branchPrefix: "lane/", // lane/1, lane/2, ... worktreeSuffix: "-lane-", // ../your-repo-lane-1 portBase: 3000, // lane n 获取 portBase + n integrationBranch: "main", // 代理落地的分支——见下文 productionBranch: null, // 设置为两阶段模型——见下文 protectedBranches: [], // 上述两个分支之外需要保护的额外分支;大多数仓库无需设置 regenerableFiles: [], // 构建工具会重写的文件——绝不因为这些文件阻止变基 symlinks: [".env", ".env.local", "node_modules"], buildOutputDirs: ["dist", "build", ".next"], // preview 不会将这些目录复制到你的工作目录 checkCommand: "npm run check", // 真正控制落地的命令——见下文 checksRequired: true, // false = 故意在没有检查的情况下运行;见下文 }; 配置格式错误(空分支名、负数端口、productionBranch 与 integrationBranch 相同等)会在任何命令加载时立即显式列出所有问题——不会在三步之后才神秘失败。 ## 🆚 对比 GitHub 的合并队列 | | GitHub 合并队列 | Claude Code Merge Queue | |—|—|—| | 私有仓库 | 仅限 Enterprise Cloud | 任何计划、任何仓库 | | 每次落地的成本 | GitHub Actions 分钟数,每次队列尝试 | $0 — 在你自己的机器上运行 | | 需要 | 一个拉取请求 | 无需 PR — 直接变基 + 推送 | 核心理念相同——序列化落地、合并前测试、保持历史整洁——但在本地运行,而不是在他人收费的云端。 ## 🧰 内含工具 | 命令 | 功能 | |—|—| | claude-code-merge-queue hook worktree-create | Claude Code 的 WorktreeCreate 钩子。将 Claude Code Merge Queue 的编号车道 (lane) 接入 Claude 原生的工作树创建流程。 | | claude-code-merge-queue build-lock -- <命令> | 执行 ``(你的构建命令)——在整个机器范围内,跨所有车道序列化。 | | claude-code-merge-queue land | 通过 FIFO 队列将你的车道变基并推送到集成分支,确保不会有两个车道同时进行推送。代理自动运行此命令。 | | claude-code-merge-queue sync | 快进主工作目录,使开发服务器能看到刚刚落地的更改——如果锁文件发生变化,还会重新安装依赖。 | | claude-code-merge-queue promote | 将集成分支推送至生产分支。仅限人工操作——绝不在代理指令中,也绝不自动化。 | | claude-code-merge-queue preview | 立即将某个车道的实时工作树(包括未提交的更改)镜像到主工作目录,让你无需构建即可查看。 | | claude-code-merge-queue port | 打印某个车道的开发服务器端口(根据其目录名称派生)。 | | claude-code-merge-queue prune | 按需移除已经落地的兄弟车道工作树。 | 推送前钩子使得 land 成为强制操作:直接 git push 到集成分支会被拒绝,并显示应实际运行的命令;钩子还会在允许落地的运行 checkCommand——若未配置 checkCommand,则默认拒绝所有推送。每个阻塞都有逃逸方式(见 🚨 紧急逃生口),但需要指定具体分支名称,而不是一个通用标志。 ### 📝 init 命令会写入哪些内容 - claude-code-merge-queue.config.mjs — 自动检测 integrationBranch 和 checkCommand。 - CLAUDE.md(或追加到已存在的文件)— 告诉 Claude Code 在检查通过后自行落地工作,无需手动指令。 - .claude/settings.json — 接入 WorktreeCreate 钩子,不影响其他已有配置。 - .husky/pre-push — 如果你已有 Husky,则创建或追加;如果没有,init 会提示你,而不是静默写入未跟踪的 .git/hooks/pre-push。 - package.json 脚本 — land、sync、promote、preview、preview:restore,跳过你已经定义过的脚本。 - claude-code-merge-queue-preflight.mjs — 一个自包含的安全网,在 land/sync 之前运行,确保过期分支能够给出真实诊断,而不是“命令未找到”。 ## 🚨 紧急逃生口 每个被阻止的推送(集成分支、productionBranch、protectedBranches 中的任何分支)都有真实的绕过方式。一个环境变量,无需提示,无需记忆第二因素: bash CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 git push origin HEAD:main 这是一个约定,而非硬性保证:它用于阻止错误和意外推送,而不是抵御主动设置该变量的恶意代理。 ## 🔍 已知限制 - 任何更改在落地前都不会经过人工审查。 checkCommand 通过是唯一的门槛——真实的测试套件和 echo ok 对此工具而言没有区别。如果你希望每次更改都有人工审批,此工具有意省略了这一步。 - 锁通过 PID 存活状态实现崩溃安全,而非超时。 kill -9 某个正在声明的进程后,下一个进程会发现该 PID 已死亡并重新获取它——无过期锁,无需调优超时。 - 单机运行,而非集群。 FIFO 队列存储在本地临时存储——两台机器同时落地时,只会遇到 Git 常规的非快进拒绝。 - 不是安全边界。 此工具的所有护栏用于阻止错误和约定偏离,而非抵御恶意代理——拥有 shell 访问权限即可 git push --no-verify 或故意修改配置。 - 慢速的 checkCommand 是真实的吞吐瓶颈。 FIFO 锁在其整个执行期间保持持有——一个 3-4 分钟的套件将限制你每小时最多落地约 20 次。 - 变基冲突会中止,不会猜测。任何冲突都会执行 git rebase --abort,工作树保持干净——CLAUDE.md 会告诉代理解决冲突后重新运行 land。 ## 📄 许可证 MIT。可以 fork、重命名、争论配置形状——这正是它的意义所在。
相似文章
在Claude Code中使用本地LLM作为代理
本文介绍了一种自定义的MCP设置,允许在同一会话中使用如llama.cpp等工具,将编码任务从Anthropic的Claude模型卸载到本地的Qwen3.8-27B模型。
我测了一下为什么在 Claude Code 里并行跑超过 3 个 agent 就会卡住
分析了为什么在 Claude Code 中运行超过三个并行 agent 会遇到瓶颈,揭示了 duty-cycle 问题——开发者成为主要延迟来源,而“合并”并行输出的过程是最大的时间成本。
多代理工作流的开源本地控制器——为Cursor、Claude Code、Codex、Antigravity会话提供统一收件箱及代理间群聊
一个名为Claude Command Center (CCC) 的开源本地面板,管理跨多个引擎(如Cursor、Claude Code、Codex和Antigravity)的多个AI编码代理会话,提供跨引擎收件箱、实时状态、git工作树生成和代理间群聊。
Show HN:adamsreview – 为 Claude Code 提供优化的多智能体 PR 审查
介绍 adamsreview,这是一个开源的 Claude Code 插件,它通过采用并行子代理、验证关卡以及自动修复循环的多智能体流水线,能够以更少的误报检测出更多 Bug,从而增强拉取请求(Pull Request)的审查效果。
@mylifcc: 分析了 Claude Code 的源码,聊聊它的异步 Agent 与工作流设计
作者剖析了 Claude Code 的源码,讲解其多 Agent 系统如何分层实现:Agent 工具、带命令队列的任务注册表、基于磁盘信箱的 teammate 团队,以及确定性的 JS 工作流引擎——所有这些都统一走共享的查询执行器,上下文彼此隔离,仅通过消息通信。