# Merge queue for AI agents: keep main green

URL: https://agentvera.dev/en/blog/merge-queue-for-ai-agents/ · Published: 2026-10-18

Why branches from parallel AI agents break main even when each one passes, what a merge queue is, and how AgentVera merges, checks and lands agent branches in order.

**In short:**

- Branches that each pass their own tests can still break main together, because each was tested against an older base.
- AgentVera’s merge queue merges each branch onto the current tip of the target branch in its own worktree and runs a check on the result.
- A conflict opens a resolver agent and a failing check gets at most two fix rounds; by default a passing branch waits for your approval before it lands.

A merge queue for AI agents is the most reliable way to keep main green once you run more than one agent at a time. With a single agent there is no drama: it works on a branch, you look at it, you merge. But when three or four agents start finishing work on their own branches, things change. Every branch passes on its own, you merge them one after another, and main is red.

This post explains why branches from parallel agents break main, how a merge queue fixes it, and how AgentVera’s merge queue works step by step.

## Green alone, red together

Start with an example. Main has a function `formatPrice(amount)`. You run two agents at the same time:

- **Agent A** adds a currency parameter: `formatPrice(amount, currency)`, and updates every call site.
- **Agent B** builds a new invoice screen that calls `formatPrice(amount)`.

Both branches started from the same main. A’s tests pass, because in A’s world the invoice screen doesn’t exist. B’s tests pass, because in B’s world the function still takes one argument. Git sees no conflict either: the two branches touched different files.

You merge A, then B. Git says nothing. But main now calls a two-parameter function with one argument, and the type check fails.

This is a semantic conflict: no textual conflict, yet the changes break each other. Parallel agents make it more common because:

- **Agents don’t see each other.** Each works in its own worktree and has no idea what the others are doing.
- **Branches pile up fast.** By mid-afternoon five or six branches can be waiting.
- **Every branch was tested on an old base.** The longer a branch waits, the staler its base.
- **Merging in order by hand is tedious.** After each merge you update the next branch, rerun the tests and fix conflicts. People start skipping it.

## What is a merge queue?

A merge queue lines up the branches waiting to land and merges each one onto the current tip of the target branch, then tests that result. The idea is simple: before a branch lands, test what main will actually look like after it lands.

How it compares to merging by hand:

| | Merging by hand | Merge queue |
| --- | --- | --- |
| What the test runs on | The branch’s own base | Current tip of main + the branch |
| Semantic conflicts | Found after they hit main | Caught before they land |
| Order | Whoever clicks first | Queue order |
| A broken branch | Breaks main | Gets rejected, main stays clean |

GitHub also has a repository-level merge queue that queues pull requests and tests them together with the latest version of the target branch. AgentVera’s queue applies the same idea on your desktop, for your agents’ branches, and adds agents that resolve merge conflicts and fix failing checks along the way.

## How AgentVera’s merge queue works

The queue lives in the desktop app under **Details → Automation → Merge queue**. Each project has one queue; in a multi-repo project each repo has its own queue and settings. Branches land one at a time.

### 1. A branch joins the queue

There are three ways in:

- **By hand:** type the branch name in the **Branch** field, optionally give it a **Title**, and press **Add to queue**.
- **From a parallel team:** when a parallel team finishes, press **Queue** to send its integration branch.
- **From an automation:** pick **Add to the merge queue** as an automation rule’s delivery, and the finished agent’s branch goes straight into the queue.

Cards in the Review inbox also offer **Send to the merge queue**. Each item shows where it came from: manual, parallel team or automation.

### 2. It merges onto the current tip of the target

When its turn comes, the branch is merged onto the target’s current tip in the queue’s own separate worktree. Your working folder and your agents’ folders are left alone. If the repo has a remote, the target is fetched first and the merge is done on top of the latest `origin` version.

You pick the strategy in the settings: **Merge commit** or **Squash**. If the branch is already contained in the target, the item is marked landed.

### 3. A conflict gets an agent

If the merge conflicts, the queue doesn’t stop. It opens a resolver agent and the item moves to “resolving conflicts”. The agent is told to keep the intent of both sides, leave no conflict markers and commit the result.

When the agent hands in, AgentVera doesn’t just take its word for it. It checks for unmerged files, scans for `<<<<<<<` and `>>>>>>>` markers and confirms the branch is really merged. If any of that fails, the item fails and does not land.

With Automatic model on, the resolver’s model is picked by how hard the job is.

### 4. The check runs on the merged result

Once the merged result is ready, the queue runs a check command. Leave **Check** empty and it uses the project’s test command, or write your own, like `pnpm typecheck && pnpm test`.

If the check fails, the resolver agent gets the tail of the output and tries to fix it. There are at most two fix rounds. If the check is still red, the item is **rejected** and the queue moves on. The broken branch never reaches main.

That is exactly what happens in the `formatPrice` example: B’s branch is merged onto a main that already has A, the type check fails, the resolver updates the invoice screen’s call to the new signature, and the check goes green.

### 5. Approval and landing

A branch that passes is ready. By default **Land passing branches automatically** is off, so the item waits as “ready, awaiting approval” and you get a notification. Take a look and press **Land** when you’re happy.

Landing works like this:

- **With a remote,** the merged result is pushed to the target branch. GitHub repos use the GitHub sign-in on your computer.
- **Without a remote,** the local target branch is fast-forwarded. It is never moved out from under uncommitted work.
- **If the target moved in the meantime,** the item is rebuilt on the new tip and checked again. That happens at most three times; if the target keeps moving, the item fails.

Close and reopen the app and work that was cut off isn’t lost; it goes back into the queue.

## Settings

There aren’t many, and they all sit in the same tab:

| Setting | What it does | Default |
| --- | --- | --- |
| Target branch | The branch work lands on | Empty: default branch |
| Merge | Merge commit or Squash | Merge commit |
| Check | Command run on the merged result | Empty: the project’s test command |
| Land passing branches automatically | Lands passing branches without approval | Off |

For queued items you can reorder with **Up** and **Down**, stop one with **Cancel**, and restart a failed or cancelled one with **Retry**. Each item has its own log and history, and items with a pull request have a button to open it on GitHub.

The queue shares resources with other background work and comes first: merges go before automations and parallel teams. Agents you start yourself are never queued.

## Parallel teams and the queue together

The merge queue pays off most with a parallel team. A parallel team splits a large job into up to eight parts; by default three agents run at once, each in its own worktree. The parts merge into an integration branch, and an integration agent handles conflicts and the check.

When the team finishes you have one integration branch. Press **Queue** to send it. Another team or an automation may have sent something to main in the meantime; the queue takes them all in order, testing each on the latest main.

For the bigger picture of working with several agents, see [parallel coding agents](/en/blog/parallel-coding-agents/).

## Common mistakes

- **An empty check and no test command.** The queue still merges, but with nothing to verify it can’t catch semantic conflicts. Define the project’s test command or put a command in **Check**.
- **Unit tests only.** Many breakages like the one above show up in the type check or the build. Add those to the check.
- **Turning on automatic landing on day one.** Don’t enable **Land passing branches automatically** before you’ve watched the queue for a while. Approve by hand for a few weeks first.
- **Huge branches.** The queue accepts them, but the odds of conflicts and failures grow with size. Give agents small, focused jobs.
- **Ignoring rejected items.** A rejection usually points to a real design clash. Read its log, and send the work back to the agent with a note if needed.

## A sample day

### Morning

You start three agents on three jobs: the checkout page, the reporting API and a dependency update. Each works in its own worktree. There is also a CI failure from last night; an automation rule already caught it and sent the fix to the queue.

### Late morning

As agents finish, you open their cards in the Review inbox. The checkout page and the reporting API look good, so you **Send to the merge queue** for both. The queue now holds three items: the CI fix, the checkout page and the reporting API.

### Noon

The CI fix passes its check and waits for approval. You press **Land**. The checkout page merges onto the new main and passes. The reporting API conflicts with a type the checkout page changed; the resolver agent steps in, updates the call sites, and the check turns green. All you did was approve twice.

### Afternoon

The dependency update is still red after two fix rounds and gets rejected. Main stays clean. The log shows a major version change in one library, so you hand the work back to an agent with narrower instructions.

## Checklist

- [ ] Does the project have a test command, or is there a command in **Check**?
- [ ] Does the check cover the type check and the build?
- [ ] Is the **Target branch** right? Empty means the default branch.
- [ ] Does the merge strategy match your team’s habit: Merge commit or Squash?
- [ ] Is **Land passing branches automatically** on or off on purpose?
- [ ] For GitHub repos, are you signed in to GitHub on this computer?
- [ ] Are your agents’ jobs small and focused?

## Wrapping up

Parallel agents are fast, but speed that breaks main doesn’t last. A merge queue merges and tests every branch on the latest main, so branches that pass alone can’t break main together. In AgentVera the queue hands conflicts and failing checks to an agent, verifies the result itself, and by default leaves the final call to you.

Read more:

- [Merge queue](/en/features/merge-queue/)
- [Parallel team](/en/features/parallel-team/)
- [Git and GitHub](/en/features/git-and-github/)
- [Git worktrees for parallel agents](/en/blog/git-worktree-parallel-agents/)
- [AI code review](/en/blog/ai-code-review/)

To try AgentVera, start at the [home page](/en/).

## Frequently asked questions

**What is a merge queue?** A merge queue lines up the branches waiting to land and merges each one onto the current tip of the target branch, then tests that merged result before it lands. Two branches that pass on their own can’t break main together.

**Why does main break when every branch passed its own tests?** Each branch was tested against an older main. If main moved in between, two changes can conflict in meaning without conflicting in text, and only testing the merged result shows it.

**What does AgentVera’s merge queue do on a conflict?** It opens a resolver agent that keeps the intent of both sides and commits. AgentVera then checks that no conflict markers are left and the branch is really merged. If not, the item fails and never lands.

**Do passing branches land on their own?** Not by default. With “Land passing branches automatically” off, a branch that passes its checks waits for your approval and lands when you press Land. You can turn the setting on.

**Which plan includes the merge queue?** The merge queue is on the Pro and Team plans. In the desktop app it lives under Details → Automation → Merge queue.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/