Claude Code Merge Queue ๐Ÿšฆ

July 29, 2026 ยท View on GitHub

Claude Code Merge Queue โ€” the local, zero-cost merge queue for parallel Claude Code agents

npm version npm downloads CI License: MIT TypeScript Node Runtime deps

Claude Code Merge Queue ๐Ÿšฆ

The local, zero-cost merge queue for parallel Claude Code agents. Several agents land, build, and test at the same time โ€” this serializes it so push races, redundant heavy builds, and shared-resource test flakiness can't happen.

โšก Quickstart

npm install --save-dev claude-code-merge-queue   # or: pnpm add -D / yarn add -D / bun add -d
npx claude-code-merge-queue init

Contents

Terminal demo: npm install --save-dev claude-code-merge-queue, then npx claude-code-merge-queue init โ€” writes the config, CLAUDE.md, the WorktreeCreate hook, and land/sync/promote/preview scripts

โš™๏ธ Configuration

Everything lives in one file โ€” see examples/claude-code-merge-queue.config.mjs for every field with comments. The short version:

export default {
  branchPrefix: "lane/",               // lane/1, lane/2, ...
  worktreeSuffix: "-lane-",            // ../your-repo-lane-1
  portBase: 3000,                      // lane n gets portBase + n
  integrationBranch: "main",           // where agents land โ€” see below
  productionBranch: null,              // set this for a two-stage model โ€” see below
  protectedBranches: [],               // extra branches beyond the two above; most repos need none
  regenerableFiles: [],                // files a build tool rewrites โ€” never block a rebase on these
  symlinks: [".env", ".env.local", "node_modules"],
  buildOutputDirs: ["dist", "build", ".next"], // preview never copies these onto your checkout
  checkCommand: "npm run check",       // what actually gates a landing โ€” see below
  checksRequired: true,                // false = deliberately run with none; see below
};

A malformed config (empty branch names, a negative port, productionBranch equal to integrationBranch, ...) fails loud with every problem listed, the moment any command loads it โ€” not a mysterious failure three steps later.

๐Ÿ†š vs. GitHub's Merge Queue

GitHub Merge QueueClaude Code Merge Queue
Private repoEnterprise Cloud onlyAny plan, any repo
Cost per landingGitHub Actions minutes, every queue attempt$0 โ€” runs on your own machine
RequiresA pull requestNothing โ€” direct rebase + push

Same idea โ€” serialize landings, test before merge, keep history clean โ€” run locally instead of in someone else's billed cloud.

๐Ÿงฐ What's in the box

CommandWhat it does
claude-code-merge-queue hook worktree-createA Claude Code WorktreeCreate hook. Plugs Claude Code Merge Queue's numbered lanes into Claude's native worktree creation.
claude-code-merge-queue build-lock -- <cmd>Runs <cmd> โ€” your build โ€” serialized across every lane, machine-wide.
claude-code-merge-queue landRebases and pushes your lane onto the integration branch through a FIFO queue, so two lanes are never mid-push at once. Agents run this themselves.
claude-code-merge-queue syncFast-forwards your main checkout so a dev server actually sees what just landed โ€” and re-installs dependencies if the lockfile changed.
claude-code-merge-queue promoteShips the integration branch to production. Human-only โ€” never in an agent's instructions, never automated.
claude-code-merge-queue previewInstantly mirrors a lane's live working tree โ€” uncommitted changes included โ€” onto the main checkout, so you can look at it without a build.
claude-code-merge-queue portPrints a lane's dev-server port, derived from its own directory name.
claude-code-merge-queue pruneRemoves already-landed sibling lane worktrees on demand.

A pre-push hook makes land non-optional: a direct git push straight to the integration branch is rejected, with the actual command to run instead, and the same hook runs checkCommand before allowing a landing through โ€” no checkCommand configured means every push fails by default. There's a way out for every block (see ๐Ÿšจ The emergency hatch), but it takes naming the specific branch, not a generic flag.

๐Ÿ“ What init writes

  • claude-code-merge-queue.config.mjs โ€” integrationBranch and checkCommand auto-detected.
  • CLAUDE.md (or appends to yours) โ€” tells Claude Code to land its own work once green, without being asked.
  • .claude/settings.json โ€” the WorktreeCreate hook wired in, without touching anything else already there.
  • .husky/pre-push โ€” created or appended to, if you already have Husky. If you don't, init tells you rather than silently writing to the untracked .git/hooks/pre-push.
  • package.json scripts โ€” land, sync, promote, preview, preview:restore, skipping any you've already defined yourself.
  • claude-code-merge-queue-preflight.mjs โ€” a self-contained safety net that runs before land/sync, so a stale branch fails with a real diagnosis instead of a bare command not found.

๐Ÿšจ The emergency hatch

Every blocked push โ€” the integration branch, productionBranch, anything in protectedBranches โ€” has a real way through it. One env var, no prompts, no second factor to remember:

CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 git push origin HEAD:main

This is a convention, not a hard guarantee: it stops mistakes and stray pushes, not an adversarial agent that sets the var itself.

๐Ÿ” Know the limits

  • No human reviews any of this before it lands. checkCommand passing is the only gate โ€” a real test suite and echo ok look identical to this tool. Want a human on every change? This is missing that step on purpose.
  • Locks are crash-safe by PID liveness, not a timeout. kill -9 anything mid-claim and the next process notices the PID is dead and reclaims it โ€” no stale locks, no timeout to tune.
  • One machine, not a fleet. The FIFO queue lives in local temp storage โ€” two machines landing at once just get git's ordinary non-fast-forward rejection.
  • Not a security boundary. Every guardrail here stops mistakes and convention drift, not an adversarial agent โ€” shell access always means git push --no-verify or editing the config on purpose.
  • A slow checkCommand is a real throughput ceiling. The FIFO lock holds for its entire duration โ€” a 3โ€“4 minute suite caps you well under 20 landings/hour.
  • Rebase conflicts abort, they never guess. git rebase --abort on any conflict, working tree left clean โ€” CLAUDE.md tells the agent to resolve it and re-run land.

๐Ÿ“„ License

MIT. Fork it, rename it, argue with the config shape โ€” that's the point.