# Claude Code Merge Queue

> A local, zero-cost merge queue CLI for serializing parallel Claude Code agent landings, preventing push races and shared-resource test flakiness.

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.

## Features
- Local FIFO merge queue for parallel Claude Code agents
- Zero runtime dependencies
- Pre-push hook enforcement blocking direct pushes to integration branch
- Configurable checkCommand gates every landing
- Crash-safe PID-based locking (no stale locks)
- WorktreeCreate hook integration with Claude Code native worktree creation
- build-lock command for machine-wide build serialization
- Numbered lane worktrees with auto-assigned dev-server ports
- Two-stage integration/production branch model
- preview command mirrors live working tree without a build
- sync command fast-forwards main checkout and reinstalls deps on lockfile change
- promote command for human-only production deploys
- Emergency bypass via environment variable
- Auto-detecting init command writes config, CLAUDE.md, hooks, and package.json scripts
- Malformed config fails loudly at load time with all problems listed
- MIT licensed, zero cost

## Integrations
Claude Code, Git, Husky, npm, pnpm, yarn, bun, GitHub Actions (CI), Node.js

## Platforms
WEB, API, CLI

## Pricing
Open Source

## Version
0.5.8

## Links
- Website: https://www.npmjs.com/package/claude-code-merge-queue
- Documentation: https://github.com/funador/claude-code-merge-queue#readme
- Repository: https://github.com/funador/claude-code-merge-queue
- EveryDev.ai: https://www.everydev.ai/tools/claude-code-merge-queue