{"slug": "show-hn-a-local-merge-queue-for-parallel-claude-code-agents", "title": "Show HN: A local merge queue for parallel Claude Code agents", "summary": "A developer released claude-code-merge-queue, a free local merge queue that serializes landings from parallel Claude Code agents to prevent push races and build flakiness. The tool runs entirely on the user's machine with zero cost, unlike GitHub's Merge Queue which requires Enterprise Cloud for private repos and charges per landing in Actions minutes.", "body_md": "**The local, zero-cost merge queue for parallel Claude Code agents.** Several\nagents land, build, and test at the same time — this serializes it so push\nraces, redundant heavy builds, and shared-resource test flakiness can't happen.\n\n```\nnpm install --save-dev claude-code-merge-queue   # or: pnpm add -D / yarn add -D / bun add -d\nnpx claude-code-merge-queue init\n```\n\n[⚙️ Configuration](#%EF%B8%8F-configuration)[🆚 vs. GitHub's Merge Queue](#-vs-githubs-merge-queue)[🧰 What's in the box](#-whats-in-the-box)[🚨 The emergency hatch](#-the-emergency-hatch)[🔍 Know the limits](#-know-the-limits)[📄 License](#-license)\n\nEverything lives in one file — see\n[ examples/claude-code-merge-queue.config.mjs](/funador/claude-code-merge-queue/blob/main/examples/claude-code-merge-queue.config.mjs) for every\nfield with comments. The short version:\n\n```\nexport default {\n  branchPrefix: \"lane/\",               // lane/1, lane/2, ...\n  worktreeSuffix: \"-lane-\",            // ../your-repo-lane-1\n  portBase: 3000,                      // lane n gets portBase + n\n  integrationBranch: \"main\",           // where agents land — see below\n  productionBranch: null,              // set this for a two-stage model — see below\n  protectedBranches: [],               // extra branches beyond the two above; most repos need none\n  regenerableFiles: [],                // files a build tool rewrites — never block a rebase on these\n  symlinks: [\".env\", \".env.local\", \"node_modules\"],\n  buildOutputDirs: [\"dist\", \"build\", \".next\"], // preview never copies these onto your checkout\n  checkCommand: \"npm run check\",       // what actually gates a landing — see below\n  checksRequired: true,                // false = deliberately run with none; see below\n};\n```\n\nA malformed config (empty branch names, a negative port, `productionBranch`\n\nequal to `integrationBranch`\n\n, ...) fails loud with every problem listed,\nthe moment any command loads it — not a mysterious failure three steps\nlater.\n\n| GitHub Merge Queue | Claude Code Merge Queue | |\n|---|---|---|\n| Private repo | Enterprise Cloud only |\nAny plan, any repo |\n| Cost per landing | GitHub Actions minutes, every queue attempt | $0 — runs on your own machine |\n| Requires | A pull request | Nothing — direct rebase + push |\n\nSame idea — serialize landings, test before merge, keep history clean — run locally instead of in someone else's billed cloud.\n\n| Command | What it does |\n|---|---|\n`claude-code-merge-queue hook worktree-create` |\nA Claude Code `WorktreeCreate` hook. Plugs Claude Code Merge Queue's numbered lanes into Claude's native worktree creation. |\n`claude-code-merge-queue build-lock -- <cmd>` |\nRuns `<cmd>` — your build — serialized across every lane, machine-wide. |\n`claude-code-merge-queue land` |\nRebases 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. |\n`claude-code-merge-queue sync` |\nFast-forwards your main checkout so a dev server actually sees what just landed — and re-installs dependencies if the lockfile changed. |\n`claude-code-merge-queue promote` |\nShips the integration branch to production. Human-only — never in an agent's instructions, never automated. |\n`claude-code-merge-queue preview` |\nInstantly mirrors a lane's live working tree — uncommitted changes included — onto the main checkout, so you can look at it without a build. |\n`claude-code-merge-queue port` |\nPrints a lane's dev-server port, derived from its own directory name. |\n`claude-code-merge-queue prune` |\nRemoves already-landed sibling lane worktrees on demand. |\n\nA pre-push hook makes `land`\n\nnon-optional: a direct `git push`\n\nstraight to\nthe integration branch is rejected, with the actual command to run\ninstead, and the same hook runs `checkCommand`\n\nbefore allowing a landing\nthrough — no checkCommand configured means every push fails by default.\nThere's a way out for every block (see 🚨 The emergency hatch), but it\ntakes naming the specific branch, not a generic flag.\n\n—`claude-code-merge-queue.config.mjs`\n\n`integrationBranch`\n\nand`checkCommand`\n\nauto-detected.(or appends to yours) — tells Claude Code to land its own work once green, without being asked.`CLAUDE.md`\n\n— the`.claude/settings.json`\n\n`WorktreeCreate`\n\nhook wired in, without touching anything else already there.— created or appended to,`.husky/pre-push`\n\n*if*you already have Husky. If you don't,`init`\n\ntells you rather than silently writing to the untracked`.git/hooks/pre-push`\n\n.—`package.json`\n\nscripts`land`\n\n,`sync`\n\n,`promote`\n\n,`preview`\n\n,`preview:restore`\n\n, skipping any you've already defined yourself.— a self-contained safety net that runs before`claude-code-merge-queue-preflight.mjs`\n\n`land`\n\n/`sync`\n\n, so a stale branch fails with a real diagnosis instead of a bare`command not found`\n\n.\n\nEvery blocked push — the integration branch, `productionBranch`\n\n, anything\nin `protectedBranches`\n\n— has a real way through it. One env var, no\nprompts, no second factor to remember:\n\n```\nCLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 git push origin HEAD:main\n```\n\nThis is a convention, not a hard guarantee: it stops mistakes and stray pushes, not an adversarial agent that sets the var itself.\n\n**No human reviews any of this before it lands.**`checkCommand`\n\npassing is the only gate — a real test suite and`echo ok`\n\nlook 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`\n\nanything 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`\n\nor editing the config on purpose.**A slow** The FIFO lock holds for its entire duration — a 3–4 minute suite caps you well under 20 landings/hour.`checkCommand`\n\nis a real throughput ceiling.**Rebase conflicts abort, they never guess.**`git rebase --abort`\n\non any conflict, working tree left clean — CLAUDE.md tells the agent to resolve it and re-run`land`\n\n.\n\nMIT. Fork it, rename it, argue with the config shape — that's the point.", "url": "https://wpnews.pro/news/show-hn-a-local-merge-queue-for-parallel-claude-code-agents", "canonical_source": "https://github.com/funador/claude-code-merge-queue", "published_at": "2026-07-30 00:20:16+00:00", "updated_at": "2026-07-30 00:52:29.242002+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["claude-code-merge-queue", "Claude Code", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/show-hn-a-local-merge-queue-for-parallel-claude-code-agents", "markdown": "https://wpnews.pro/news/show-hn-a-local-merge-queue-for-parallel-claude-code-agents.md", "text": "https://wpnews.pro/news/show-hn-a-local-merge-queue-for-parallel-claude-code-agents.txt", "jsonld": "https://wpnews.pro/news/show-hn-a-local-merge-queue-for-parallel-claude-code-agents.jsonld"}}