claude-code-merge-queue: A Local Merge Queue for Parallel AI Agents

Local Serialization for Parallel AI Agents

claude-code-merge-queue is a local, zero-cost merge queue designed to manage multiple parallel Claude Code agents working on a single codebase. It prevents common concurrency issues—such as push races, redundant heavy builds, and shared-resource test flakiness—by serializing the process of landing, building, and testing code changes.

Unlike cloud-based merge queues, this tool runs entirely on the developer's local machine, removing the need for paid Enterprise plans or GitHub Actions minutes for every queue attempt.

Core Functionality and Commands

The tool integrates directly with Claude Code's native worktree creation and provides a suite of commands to manage the lifecycle of agent-driven changes:

Landing and Synchronization

  • land: Rebases and pushes a lane onto the integration branch via a First-In-First-Out (FIFO) queue. This ensures that two agents never attempt to push simultaneously.
  • sync: Fast-forwards the main checkout to reflect the latest landed changes and re-installs dependencies if the lockfile has changed.
  • promote: A human-only command used to ship the integration branch to production. This is explicitly excluded from agent instructions to prevent automated production deployments.

Development and Maintenance

  • build-lock: Runs a specified build command serialized across all lanes on the machine to prevent resource contention.
  • preview: Mirrors a lane's live working tree (including uncommitted changes) onto the main checkout for immediate human inspection without requiring a full build.
  • port: Calculates and prints the dev-server port for a specific lane based on its directory name.
  • prune: Cleans up worktrees from lanes that have already landed.

Technical Implementation and Guardrails

Configuration and Setup

Initialization via npx claude-code-merge-queue init configures the environment by creating a claude-code-merge-queue.config.mjs file and updating CLAUDE.md to instruct agents to land their own work once tests pass. It also wires in a WorktreeCreate hook into .claude/settings.json and sets up pre-push hooks (via Husky if available) to ensure that land is used instead of direct git push to protected branches.

Safety Mechanisms

  • The Emergency Hatch: To bypass blocks on protected branches, users can use the environment variable CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 during a git push. This is a convention-based guardrail rather than a security boundary.
  • Crash-Safe Locking: Locks are managed by PID liveness. If a process is killed (e.g., kill -9), the next process detects the dead PID and reclaims the lock, eliminating the need for timeouts.
  • Conflict Handling: If a rebase conflict occurs during the land process, the tool executes git rebase --abort and leaves the working tree clean. The agent is then instructed via CLAUDE.md to resolve the conflict and re-run the command.

Comparison: Local vs. Cloud Merge Queues

Feature GitHub Merge Queue Claude Code Merge Queue
Private Repo Support Enterprise Cloud only Any plan, any repo
Cost GitHub Actions minutes per attempt $0 (Local execution)
Requirement Requires a Pull Request Direct rebase + push

Constraints and Limitations

  • Lack of Human Review: The checkCommand (e.g., npm run check) is the only gate. If the command passes, the code lands. There is no built-in mechanism for human approval before merging.
  • Single-Machine Scope: The FIFO queue is stored in local temporary storage. If multiple machines attempt to land changes simultaneously, they will encounter standard Git non-fast-forward rejections.
  • Throughput Ceiling: The total number of landings per hour is limited by the duration of the checkCommand. A 4-minute test suite, for example, would cap throughput at under 20 landings per hour.
  • Security: The tool is not a security boundary; users with shell access can still bypass hooks using git push --no-verify.

Community Perspectives

Users in the community have suggested alternative approaches to managing agent concurrency, such as using jj (Jujutsu) instead of Git to handle worktrees and branches more fluidly, or implementing custom deployment systems that use content-based digests to bypass redundant tests. Some developers noted that for small-scale operations, isolated worktrees per conversation combined with an orchestrator agent can achieve similar results without a dedicated merge queue tool.

Sources