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 許可證，允許自由使用、修改和分發。