Claude Code Merge Queue

Claude Code Merge Queue is an open-source npm package built by Jesse Heaslip (GitHub: funador) that solves a specific problem in multi-agent AI coding workflows: when several Claude Code agents work in parallel git worktrees, they can race each other to push, trigger redundant builds, and cause flaky tests from shared resources. This tool serializes those landings through a local FIFO queue, running checks before any agent's work merges into the integration branch. It is published under the MIT license and requires Node.js ≥ 18.

What It Is

Claude Code Merge Queue is a CLI tool that acts as a local alternative to GitHub's Merge Queue feature, designed specifically for teams running parallel Claude Code agents. Instead of relying on GitHub Actions minutes or requiring Enterprise Cloud access, it runs entirely on your own machine. The core idea is the same as a hosted merge queue — serialize landings, test before merge, keep history clean — but executed locally at zero cost. It integrates directly with Claude Code's native WorktreeCreate hook and git's pre-push mechanism to enforce the queue without requiring manual intervention from agents.

How the Queue Works

Each agent operates in a numbered "lane" — a separate git worktree with its own branch (e.g., lane/1, lane/2) and dev-server port (derived from a configurable portBase). When an agent finishes its work, it runs claude-code-merge-queue land, which:

• Claims a FIFO lock (crash-safe by PID liveness, not a timeout)
• Rebases the lane onto the integration branch
• Runs the configured checkCommand (e.g., npm run check)
• Pushes only if checks pass

A pre-push hook blocks any direct git push to the integration branch, redirecting to the land command. The build-lock subcommand additionally serializes heavy build steps machine-wide across all lanes.

Command Surface

The package ships eight commands covering the full agent lifecycle:

• hook worktree-create — wires Claude Code's native worktree creation into the lane numbering system
• land — the primary agent command; rebase, check, push through the FIFO queue
• sync — fast-forwards the main checkout after a landing, reinstalling deps if the lockfile changed
• promote — ships the integration branch to production; explicitly human-only, never automated
• preview — mirrors a lane's live working tree (including uncommitted changes) onto the main checkout without a build
• port — prints a lane's dev-server port
• prune — removes already-landed lane worktrees
• build-lock — serializes any command machine-wide across lanes

Setup Path

Installation is a two-step process: npm install --save-dev claude-code-merge-queue followed by npx claude-code-merge-queue init. The init command auto-detects the integration branch and check command, then writes a config file, appends to or creates CLAUDE.md (instructing Claude Code to land its own work once green), wires the WorktreeCreate hook into .claude/settings.json, and adds land, sync, promote, and preview scripts to package.json. If Husky is present, it appends to .husky/pre-push; if not, it reports that rather than writing to an untracked hook file.

Tradeoffs to Know

The README is explicit about the tool's intentional limitations:

• No human review gate — checkCommand passing is the only merge gate; a real test suite and echo ok are indistinguishable to the tool
• Single-machine scope — the FIFO queue lives in local temp storage; two machines landing simultaneously fall back to git's ordinary non-fast-forward rejection
• Throughput ceiling — the FIFO lock holds for the entire checkCommand duration; a 3–4 minute test suite caps throughput well under 20 landings/hour
• Not a security boundary — the guardrails stop mistakes and convention drift, not an adversarial agent with shell access

An emergency escape hatch (CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1) allows bypassing any blocked push when needed.

Update: v0.5.8

The latest release is v0.5.8, published on 2026-07-29. The repository was created on 2026-07-10 and has shipped 18 versions in its first few weeks, indicating active early development. The project has zero runtime dependencies and is written in TypeScript 5.x.