Show HN：為並行 Claude Code 代理設計的本地合併佇列

本篇文章介紹了一個名為 Claude Code 合併佇列的開源工具，它旨在解決多個 Claude Code 代理並行工作時可能出現的推送衝突、重複構建和測試不穩定問題。該工具在本地執行，無需額外成本，適用於任何 GitHub 倉庫。

快速開始

您可以透過 npm 安裝：npm install --save-dev claude-code-merge-queue，然後執行 npx claude-code-merge-queue init 進行初始化。

配置

所有配置都儲存在一個檔案中，例如 claude-code-merge-queue.config.mjs。主要配置項包括：branchPrefix、worktreeSuffix、portBase、integrationBranch、productionBranch、protectedBranches、regenerableFiles、symlinks、buildOutputDirs、checkCommand 和 checksRequired。配置錯誤會立即提示，避免後續難以排查的問題。

與 GitHub 合併佇列的比較

GitHub 的合併佇列僅適用於 Enterprise Cloud 使用者，且每次著陸都會消耗 Actions 分鐘數。而 Claude Code 合併佇列則在本地執行，免費使用，不要求建立拉取請求。

命令列表

工具提供了多個命令：claude-code-merge-queue hook worktree-create 用於建立工作目錄；build-lock 用於序列化構建；land 用於透過 FIFO 佇列將分支推送到整合分支；sync 用於同步主分支；promote 用於將整合分支推送到生產環境（僅限人類操作）；preview 用於即時檢視分支的工作樹；port 列印開發伺服器埠；prune 清理已著陸的分支分支。此外，預推送鉤子強制執行 land 命令，並確保 checkCommand 透過。

初始化

執行 init 命令會生成配置檔案、更新 CLAUDE.md、配置工作目錄鉤子、設定 Husky 鉤子，並新增 npm 指令碼。同時生成一個預檢指令碼，用於在著陸前檢查分支狀態。

緊急出口

當推送被阻止時，可以透過設定環境變數 CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 來繞過保護。這是一個約定而非硬性保證，主要防止意外錯誤。

侷限性

該工具沒有人工審查環節，checkCommand 是唯一的門控。鎖機制基於 PID 存活狀態，而非超時，因此 kill -9 後會自動回收。目前僅支援單機執行，不支援叢集。它不是一個安全邊界，只能防止意外而非惡意操作。如果 checkCommand 執行時間較長，吞吐量會受限（例如 3-4 分鐘的測試套件導致每小時少於 20 次著陸）。如果發生合併衝突，工具會自動中止並提示代理解決。

許可

專案採用 MIT 許可證，允許自由使用、修改和分發。