If you run more than one Claude Code agent against the same repo at once, you already know the failure mode: two agents finish at the same time, both push, and one of them stomps the other, or a build starts compiling code that's already stale by the time it finishes. Add a third or fourth lane and the odds of a collision climb fast, because nothing is telling the agents to take turns. A local merge queue for parallel Claude Code agents fixes that by making every landing wait in line instead of racing for the same branch, and by giving each agent its own isolated workspace so a half-finished change in one lane never leaks into what another lane is testing.
Short answer:
claude-code-merge-queueis a free, open-source npm package that gives each Claude Code agent its own git worktree "lane," then serializes builds and pushes through a FIFO queue with crash-safe, PID-based locks. Install it withnpm install --save-dev claude-code-merge-queue, runnpx claude-code-merge-queue init, and it wires yourCLAUDE.mdand pre-push hook automatically.
I installed the tool (`funador/claude-code-merge-queue`, MIT-licensed, currently at version 0.5.8) in a scratch repo and ran three Claude Code sessions against it side by side to see whether it actually stops the collisions it promises to stop. Here's what it needs, the exact setup, and the two limits I'd want a reader to know before betting a real project on it.
What you'll need
Node.js 18 or newer and a git repository that supports worktrees — which almost any modern git install does. You'll need Claude Code itself, on a paid plan, since it's a Claude Code integration rather than a standalone build tool. The package has zero runtime dependencies (its only devDependencies are @types/node, tsx, and typescript, used to build the CLI itself), so there's nothing else to install or configure on your machine beyond npm. It's built for one machine running multiple agent worktrees, not a distributed fleet across several computers — keep that in mind if your setup spans more than one box.
Step-by-step: setting up the merge queue
1. Install the package
From your project root:
“ npm install --save-dev claude-code-merge-queue “
This adds the CLI as a dev dependency only — nothing ships to production.
2. Run init and check the generated config
“ npx claude-code-merge-queue init “
In my test, init auto-detected my integration branch and test command without me typing either one, then wrote a single claude-code-merge-queue.config.mjs file with the branch prefix, worktree naming, port allocation, and a list of protected branches. It also updated CLAUDE.md with landing instructions, added a .husky/pre-push hook, and dropped new npm scripts for each command.
3. Give each agent its own lane
Start a Claude Code session per lane (lane/1, lane/2, and so on). Each lane is its own git worktree with its own dev-server port, calculated as your configured base port plus the lane number — so two agents never collide on localhost:3000 while testing changes.
4. Land through the queue instead of pushing directly
When an agent finishes a change, it runs the land command rather than git push. That command rebases the lane onto the integration branch and pushes through a FIFO queue, so only one lane is ever mid-push at a time — the second agent's land call simply waits.
5. Sync your main checkout and promote when ready
Run sync to fast-forward your main working copy — it reinstalls dependencies automatically if the lockfile changed underneath it. promote is deliberately left as a human-only step in this tool; it ships the integration branch to production, and no agent is meant to call it on its own.
Example prompts you can copy
These are the prompts I actually used across my three test lanes, once the queue was wired in:
- "Land this change through the merge queue, and if the rebase conflicts, stop and show me the conflicting hunks instead of guessing."
- "Check the queue status before you start — if another lane is mid-land, keep working on the next task instead of blocking."
- "Run
syncbefore you start this task so you're branching off what actually landed, not what you last saw." - "After you land, run
pruneto remove your lane so it doesn't sit around stale."
The common thread: tell the agent to use the queue's commands explicitly (land, sync, prune) rather than assuming it'll reach for git push on its own, since CLAUDE.md only nudges it — it doesn't force the behavior.
Common mistakes to avoid
The one that got me on my first run: skipping sync before starting new work, so an agent branched off a stale main and its rebase during land hit conflicts that didn't need to happen. Second, assuming the queue reviews code — it doesn't. Landing only requires your configured checkCommand to pass; there's no human gate unless you add one yourself, so a broken feature can still land cleanly if your tests don't catch it. Third, running agents across two separate machines and expecting the queue to coordinate them — the FIFO queue and PID locks are local-only, so a second machine pushing at the same time just hits git's normal non-fast-forward rejection instead of waiting politely. Fourth, forgetting the emergency override exists (CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 git push origin HEAD:main) and manually disabling the pre-push hook instead — the env var bypass is scoped to one push and easier to audit later.
How it compares to other ways to coordinate parallel agents
| Approach | Cost | Where locks/checks run | Stops push races? | Needs CI |
|---|---|---|---|---|
claude-code-merge-queue |
Free, MIT, open source | Your machine (PID-based) | Yes — FIFO queue, one lane pushes at a time | No |
| Manual git worktrees, no tooling | Free | Nowhere — first push wins | No — races and duplicate builds still happen | No |
| GitHub's native merge queue | Free on public org repos; Enterprise Cloud only for private repos | GitHub's servers | Yes, but only at PR-merge time, not local agent landings | Yes, per GitHub’s docs |
| One Claude Code session at a time | Free | N/A — no parallelism to coordinate | Not applicable | No |
If you're only running one agent, none of this matters — the problem is specific to parallel lanes. If you're running parallel agents but pushing to GitHub with required checks anyway, GitHub's own merge queue and this local one aren't competitors; they solve different stages, and using both isn't redundant.
Tools that make this easier
None of this replaces knowing Claude Code itself well first — my how to use Claude AI guide covers accounts and prompting basics if you're newer to the ecosystem, and my /mission for Claude Code piece covers the companion problem of giving each lane consistent standing context via CLAUDE.md and skills. If you're trying to figure out how many parallel agents you can actually afford to run, Claude Code usage tracking by LangWatch is the closest thing to a cost dashboard for exactly that. Since the model underneath does most of the heavy lifting when three lanes are working at once, my Claude Opus 5 review covers what changed and whether it's worth running for this kind of concurrent, agentic work. If you're weighing Claude Code against other agentic editors before committing to a multi-lane setup, Cursor vs Copilot and my broader best AI tool for code roundup cover the alternatives.
My take
This is a genuinely useful, narrow tool, and the fact that it's free and has zero runtime dependencies makes it low-risk to try. What I'd flag before anyone adopts it on a real project: it's single-machine only, it doesn't review code, and throughput is capped by how long your test suite takes — a 3-4 minute suite caps you at under 20 landings an hour, no matter how many agents you're running. That's fine for a solo developer juggling three or four Claude Code lanes on one laptop, which is exactly the use case it was built for. It's the wrong tool if you need a distributed team of agents across machines or a real code-review gate — for that, pair it with your existing CI and required reviews rather than expecting the queue to replace them.
I also came away thinking the emergency-override flag is a smart bit of design, not just an escape hatch. Plenty of internal tools bolt on a "break glass" option that quietly turns off every safety check at once and never gets audited. Scoping the override to a single git push call, gated behind an environment variable you have to type on purpose, means a stressed-out 2 a.m. push still leaves a trail instead of silently disabling the pre-push hook for good.
Frequently Asked Questions
Is the local merge queue for parallel Claude Code agents free?
Yes. claude-code-merge-queue is MIT-licensed and free on npm, with zero runtime dependencies. You still need a paid Claude Code plan to run the agents themselves.
How long does setup take?
About five minutes in my test: npm install, then npx claude-code-merge-queue init, which auto-detected my integration branch and test command and wrote the config, CLAUDE.md update, and pre-push hook without extra prompts.
What is the easiest way to try this?
Run init in a low-stakes scratch repo first with two lanes, land a trivial change from each, and watch the FIFO queue serialize the pushes before you point it at a real project.
Does it review code before it lands?
No. The only gate is your configured checkCommand passing — there's no human review step built in, so you still need your own CI checks or manual review for anything you don't want landing on a green test run alone.
Can it coordinate agents running on two different machines?
No. The FIFO queue and PID-based locks are local to one machine. Across machines, a second push during a land attempt just gets git's normal non-fast-forward rejection, per the project’s GitHub README.