Merge queue for AI agents: keep main green

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:

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:

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.

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
• Parallel team
• Git and GitHub
• Git worktrees for parallel agents
• AI code review

To try AgentVera, start at the home page.