Serialize parallel Claude Code agent merges with local queue

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

• ⚙️ Configuration
• 🆚 vs. GitHub's Merge Queue
• 🧰 What's in the box
• 🚨 The emergency hatch
• 🔍 Know the limits
• 📄 License

⚙️ 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

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

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.

examples/claude-code-merge-queue.config.mjs

// claude-code-merge-queue.config.mjs — lives at your repo root. `claude-code-merge-queue init` writes a
// copy of this for you; edit the values below for your project.
//
// Worktree isolation is Claude Code's job (native `--worktree` /
// `isolation: "worktree"`) — this file is what the WorktreeCreate hook
// (see hooks/claude-settings.example.json) reads to name and shape the lane
// it creates, and what everything downstream (build queue, landing queue,
// preview) reads too.

/** @type {import("claude-code-merge-queue").ClaudeCodeMergeQueueConfig} */
export default {
  // Lane branches: lane/1, lane/2, ...
  branchPrefix: "lane/",

  // Sibling worktree dirs: ../<your-repo>-lane-1, -lane-2, ...
  worktreeSuffix: "-lane-",

  // Lane 1 gets this port, lane 2 gets portBase + 2, and so on — handy if
  // each lane also runs its own throwaway dev server.
  portBase: 3000,

  // The branch `claude-code-merge-queue land` rebases onto and pushes to. Agents land
  // here continuously and autonomously — see the CLAUDE.md workflow section
  // `claude-code-merge-queue init` writes.
  integrationBranch: "main",

  // Set this if you run a two-stage model: agents land on integrationBranch,
  // a human ships to productionBranch on their own schedule with
  // `claude-code-merge-queue promote`. null (the default) means integrationBranch IS
  // production — no separate promotion step. Example: integrationBranch
  // "dev", productionBranch "main". Automatically protected by the pre-push
  // hook when set — you don't need to also list it below.
  productionBranch: null,

  // Extra branches the pre-push hook refuses a *direct* push to, beyond
  // integrationBranch and productionBranch. Most repos need nothing here.
  protectedBranches: [],

  // Files your build tool rewrites on its own that should never block a
  // rebase or a fast-forward. Next.js projects typically want
  // ["next-env.d.ts"] here at minimum — add to this list the first time a
  // regenerated file blocks a landing, and never think about it again.
  regenerableFiles: [],

  // UNTRACKED session litter (a scratchpad of run logs, a temp dir) that's
  // safe to `git clean` when reclaiming a lane whose branch already landed and
  // that no live session is in. Without this, one stray untracked file pins an
  // otherwise fully-landed, abandoned lane on disk forever (git worktree remove
  // refuses on ANY untracked file). Empty by default — nothing untracked is
  // ever deleted until you name it here; anything unlisted still blocks pruning
  // and is surfaced as real uncommitted work. e.g. ["scratchpad/"].
  disposableUntracked: [],

  // Git-ignored paths symlinked into every new lane so it needs no fresh
  // install and no copy of your secrets.
  symlinks: [".env", ".env.local", "node_modules"],

  // Build-output dirs `claude-code-merge-queue preview` never copies onto your dev
  // checkout. preview is framework-agnostic (it's an rsync, not a build
  // step) — this is the one place your framework's name shows up. Add
  // ".output" for Nuxt, ".svelte-kit" for SvelteKit, etc.
  buildOutputDirs: ["dist", "build", ".next"],

  // The command that actually gates a landing — your lint/typecheck/test/
  // build. `claude-code-merge-queue init` tries to detect this from package.json
  // (check:push, check, ci, or test, in that order) and fills it in for
  // you. null means nothing runs, which is only allowed if checksRequired
  // is also false — see below.
  checkCommand: "npm run check",

  // true (the default): a null checkCommand FAILS every push rather than
  // landing unverified code. Set to false yourself to deliberately run
  // with no checks — a real state for a repo with nothing to test yet, but
  // one that should be a visible, committed choice, not a silent default.
  checksRequired: true,
};