A local merge queue for parallel AI agents, and why it matters

A local merge queue for parallel Claude Code agents is not a phrase I expected to read this week, but it solves a problem I hit on my own hardware every day. The project is claude-code-merge-queue, posted to Hacker News on 30 July 2026 by its author, who says they push up to 90 commits a day from 4-5 parallel agents on an 8GB MacBook Air.

The interesting part is not the queue. It is what the constraint forced.

---

🧩 What the thing actually does

Strip the branding and it is a scheduler for your own machine. Each agent gets its own git worktree (a "lane"), so five agents can edit five checkouts of the same repo without stepping on each other. When a lane wants to land its work, it joins a FIFO queue guarded by PID-based file locks, rebases onto the integration branch, runs the configured check command, and pushes. One at a time.

Command	What it does
land	Rebase + push the lane through the FIFO queue
build-lock -- <cmd>	Serialise a build so only one lane compiles at a time
sync	Fast-forward the main checkout, reinstall if the lockfile changed
preview	Mirror a lane's working tree onto the main checkout
promote	Move integration branch to production (human-only)
port	Print the lane's dev-server port
prune	Delete worktrees for lanes that already landed

Setup is two commands (npm install --save-dev claude-code-merge-queue then npx claude-code-merge-queue init), and init writes the config, a CLAUDE.md, a .claude/settings.json hook, a .husky/pre-push hook and npm scripts. Licence is MIT.

The lock design is the detail I liked most. Locks check whether the holding PID is still alive instead of expiring on a timeout, so a force-quit releases the queue immediately rather than blocking everyone for five minutes.

---

💰 Why "local" is the entire point for us

Two costs get avoided here, and only one of them is money.

	Cloud merge queue	This local queue
Availability	GitHub Enterprise Cloud tier	Any repo, any machine
Cost per attempt	Billed CI minutes (USD)	Free
Requires a PR	Yes	No, works on direct rebases
Works offline	No	Yes
Human review gate	Yes, if configured	None

For a developer billing in rupees, CI minutes are a USD-denominated subscription against an LKR salary. Ninety pushes a day through a cloud pipeline is not a rounding error. And a failed build at 11pm on a metered connection costs you twice: the minutes and the download.

Key takeaway: The scarce resource for most Sri Lankan developers is not AI capability, it is RAM and USD. Tools that trade cloud spend for local scheduling are worth more here than they are in San Francisco.

I feel this one directly. The build pipeline behind this site runs on a shared 4-core box with under 8GB free, and two concurrent Next.js builds reliably kill it. My fix was crude: a lock file that refuses to start a second build. This project is the same instinct, done properly, with worktree isolation and per-lane dev-server ports on top.

If you are budgeting agent runs before you start, our AI agent cost calculator will get you closer than guessing.

---

⏱️ The throughput maths nobody puts on the landing page

The README is honest about the ceiling, which I respect. Serialising landings means your test suite becomes the bottleneck for the whole team of agents.

The stated figure: a 3-4 minute check suite caps you at roughly 20 landings per hour. Work it through:

• 5 agents, each producing a landable change every 10 minutes, want 30 landings/hour.
• The queue can serve about 20.
• The other 10 sit in line. Your agents are now waiting on your test suite, not on the model.

Which means the real upgrade path is not more agents. It is a faster checkCommand:

1. Split unit tests from integration tests, and run only unit tests on land.
2. Cache dependencies so sync does not reinstall on every lockfile touch.
3. Cut the slowest 10% of tests, or move them to a nightly run.
4. Only then add a sixth agent.

Adding parallelism upstream of a serial bottleneck just grows the queue. That is Little's Law, not a Claude Code problem.

---

⚠️ What I would be careful about

Three things stand out, all of them stated plainly in the README rather than hidden.

No human reviews occur before landing. The only gate is whether checkCommand passes.

That is a real posture change. Your test suite is now your code reviewer. If coverage is thin, ninety unreviewed commits a day is ninety chances to ship something confidently wrong. The promote step being human-only is the mitigation, and I would not disable it.

• It is not a security boundary. The author says so directly. An agent with shell access still has shell access.
• Single machine only. The queue lives in local temp storage, so it does not coordinate across your laptop and your VPS.
• Rebase conflicts abort cleanly, but an agent still has to resolve them, and agents resolving their own conflicts unsupervised is where I would want a human looking.

There is also an emergency escape hatch, CLAUDE_CODE_MERGE_QUEUE_EMERGENCY_PUSH=1 git push, for when the queue itself is the thing that is broken. Good design includes a way out.

---

💡 What this means for you

If you are a student or a solo builder on an 8GB machine, the lesson is portable even if you never install this package:

• Isolate with worktrees, not clones. Same repo, separate working directories, no duplicated .git.
• Serialise the expensive step. One build at a time beats four builds and a swap-death.
• Make PIDs your timeout. Liveness checks beat arbitrary lock expiry.
• Treat your test suite as the throughput budget. It sets your ceiling before your hardware does.

The broader signal is that constraint-driven tooling is becoming a category. Someone on modest hardware hit a wall, wrote a fix, and open-sourced it under MIT. That path is wide open to Sri Lankan developers, and the constraints we build under are shared by most of the world, not the minority that has an Enterprise Cloud budget.

If you try it, my advice: start with two lanes, measure how long land actually takes, and only scale up once your check suite is fast enough to keep up.