claude-code-merge-queue：平行 AI 代理的本地合併佇列

平行 AI 代理的本地序列化

claude-code-merge-queue 是一個本地、零成本的合併佇列，旨在管理多個同時執行的 Claude Code 代理在單一程式碼庫上的工作。它透過序列化落地、建置與測試程式碼變更的流程，防止常見的併發問題——例如推送競爭、冗餘的繁重建置，以及共享資源測試的不穩定性。

與基於雲端的合併佇列不同，此工具完全在開發者的本機上執行，免除每次佇列嘗試所需的付費 Enterprise 計畫或 GitHub Actions 分鐘。

核心功能與指令

此工具直接整合 Claude Code 原生的 worktree 建立，並提供一系列指令來管理代理驅動變更的生命週期：

落地與同步

  • land：將 lane 以先進先出 (FIFO) 佇列的方式 rebase 並推送至整合分支。確保兩個代理不會同時嘗試推送。
  • sync：快進主檢出以反映最新的落地變更，若 lockfile 有變更則重新安裝相依套件。
  • promote：僅供人工使用的指令，用於將整合分支部署至正式環境。此指令明確排除在代理指示之外，以防止自動化的正式部署。

開發與維護

  • build-lock：在機器上對所有 lane 序列化執行指定的建置指令，以避免資源競爭。
  • preview：將 lane 的即時工作樹（含未提交的變更）鏡像到主檢出，讓人類即時檢視，無需完整建置。
  • port：根據目錄名稱計算並輸出特定 lane 的開發伺服器埠號。
  • prune：清除已落地 lane 的 worktree。

技術實作與防護措施

設定與安裝

透過 npx claude-code-merge-queue init 進行初始化，會建立 claude-code-merge-queue.config.mjs 檔案，並更新 CLAUDE.md 以指示代理在測試通過後自行落地。此過程亦會在 .claude/settings.json 中加入 WorktreeCreate 鉤子，並設定 pre‑push 鉤子（若有 Husky）以確保使用 land 而非直接 git push 到受保護分支。

安全機制

  • 緊急開關：若需繞過受保護分支的阻擋，使用者可在 git push 時設定環境變數 CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1。這是一種基於慣例的防護措施，而非安全邊界。
  • 崩潰安全鎖：鎖定由 PID 存活狀態管理。若進程被終止（例如 kill -9），下一個進程會偵測到死亡的 PID 並重新取得鎖，免除超時機制的需求。
  • 衝突處理：若在 land 過程中發生 rebase 衝突，工具會執行 git rebase --abort，保持工作樹乾淨。之後代理會透過 CLAUDE.md 被指示解決衝突並重新執行指令。

比較：本地與雲端合併佇列

功能 GitHub Merge Queue Claude Code Merge Queue
私有倉庫支援 僅限 Enterprise Cloud 任意方案、任意倉庫
成本 每次嘗試消耗 GitHub Actions 分鐘 $0（本地執行）
需求 需要 Pull Request 直接 rebase + push

限制與局限

  • 缺乏人工審核：checkCommand（例如 npm run check）是唯一的關卡。只要指令通過，程式碼即落地。沒有內建的人為批准機制。
  • 單機範圍：FIFO 佇列儲存在本機暫存空間。若多台機器同時嘗試落地變更，會遭遇標準的 Git non‑fast‑forward 拒絕。
  • 吞吐上限：每小時的落地次數受 checkCommand 執行時間限制。例如 4 分鐘的測試套件，吞吐量上限約為每小時不到 20 次落地。
  • 安全性：此工具不是安全邊界；具有 shell 存取權的使用者仍可透過 git push --no-verify 繞過鉤子。

社群觀點

社群中的使用者提出了管理代理併發的替代方案，例如使用 jj（Jujutsu）取代 Git，以更靈活地處理 worktree 與分支，或實作使用內容雜湊繞過冗餘測試的自訂部署系統。有開發者指出，對於小規模運作，將每次對話的 worktree 隔離，搭配一個協調代理，即可在不需要專屬合併佇列工具的情況下達成類似效果。

Sources