funador/claude-code-merge-queue: The local merge queue for parallel Claude Code agents · GitHub

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.

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

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

export default 🔥;

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.

Same idea — serialize landings, test before merge, keep history clean — run
locally instead of in someone else’s billed cloud.

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.

• 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.

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.

• 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.

MIT. Fork it, rename it, argue with the config shape — that’s the point.