MergeLoop

The build lane: issues built on your machines

The build lane

The build lane turns labeled issues into merged PRs on your developers’ own machines. Someone puts the repo’s label on an issue written as a brief an agent can act on. A developer’s daemon, mergeloop daemon, claims it, has an agent CLI on their machine (Claude Code or Codex, signed in with their own login) build it in a fresh worktree, runs the repo’s verify commands, has a second agent review the change, and pushes it. MergeLoop’s App opens the PR, labeled, so it is queued, and the daemon lands it like any PR: it works the review’s threads and what the PR needs until it merges. The Builds page shows each build, who holds it and how far it is.

The lane is off until a workspace turns it on. It changes nothing for PRs people open. MergeLoop never approves a PR it built, since its App is the PR’s author: what may merge with no human is up to the repo’s rules (see Dark merges).

What an agent may do on your machine

Read this before you run the daemon. The daemon runs agents, and the commands they write, on your machine, from the text of an issue that anyone who can open issues in the repo may have written. Label only issues you would hand to an agent on your own machine.

access in the config file picks how far a build is confined. A build is everything that runs for it: the agent, the commands the agent runs, and the repo’s verify commands, which the agent may have changed.

access = "workspace" (default)access = "full"
WritesOnly the build’s own folder, builds/<build>/ in the daemon’s folder: its worktree and its temp folder. Not your checkouts, other builds, the clones’ git metadata, the transcripts or the daemon’s own files.Anything you can write
ReadsAnything you can read, except the deny_read paths: by default your MergeLoop session and the places credentials live in a home folderAnything you can read
PromptsNone: the agent works without askingNone
macOSThe agent CLI’s own sandbox (Claude Code’s, Codex’s permission profile), and sandbox-exec for the verify commands. Checked on this platform.
LinuxThe agent CLI’s own sandbox (Claude Code’s needs bubblewrap and socat), and bwrap for the verify commands. The CLIs’ read denials there are their documented behaviour, not checked by MergeLoop.
ElsewhereRefused when the daemon starts

What nothing stops, in either mode:

An agent can also open your browser at a MergeLoop sign-in, as any program on your machine can. MergeLoop gives it nothing until you allow that sign-in on its page, and the page shows the code that mergeloop login prints, so you can tell your own sign-in from one you did not start. Allow only a sign-in you started: a yes to one you did not start gives that program a session that acts as you.

The daemon prints what does not hold on your platform when it starts. The details below say how each part is confined.

Turn it on

  1. In Settings, turn on Build lane, or call set_build_settings. While it is off, no daemon gets a new task, every lane tool but its settings refuses, and the Builds page says how to start. Turning it off is no stop button. It forgets the issues waiting and the builds merged. A daemon stops a build it holds when it next talks to MergeLoop, which can take as long as its heartbeat interval (5 minutes), and throws away that build’s work it has not pushed. The build’s record is kept: once the lane is on again, the build is a task again (when its daemon restarts, or once it goes 30 minutes unheard) and is built anew, or, when it has a PR, landed again. A PR that is already open stays in the queue and can still merge.
  2. Put the repo’s label (its label setting, mergeloop by default) on an issue. An issue is a task while it is open and labeled, in a repo whose queue runs. A self-hosted App created before the issues event joined its events must be subscribed to it, as Run it with an App you made yourself says; until then a labeled issue becomes a task within 5 minutes of a daemon asking for work, rather than at once.
  3. On each machine that builds, install the mergeloop command and run mergeloop login once. Install the builder’s agent CLI (Claude Code by default) and sign in to it, as mergeloop login does not. Do the same for the reviewer’s: unless the config file names one, the reviewer is the other vendor’s CLI when it is on your PATH (Codex for a Claude builder), else the builder’s own. A CLI that is on your PATH but not signed in must be signed in, or the reviewer set in [reviewer] (agent, command), or turned off (enabled = false). Then run mergeloop daemon. It prints the builder’s and the reviewer’s commands when it starts: check them before its first build.

Only a developer whom GitHub lets push to a repo is given its tasks, and a token for it: an issue assigned to them goes to their daemon first, then unassigned ones; an issue assigned to someone else is never given to them. When a daemon claims an unassigned issue, MergeLoop assigns the developer on GitHub, for people to see who has it.

Run the daemon

mergeloop daemon signs in with the session from mergeloop login (never MERGELOOP_TOKEN or gh’s token) and serves every workspace you belong to that has the lane on, until Ctrl-C. While it has a free slot, it claims a task and builds it:

  1. In its own clone of the repo and a fresh worktree, on the branch mergeloop/build-<issue>, the builder agent builds the issue.
  2. The repo’s verify commands, as its config file declares them, must pass; when they fail, the agent gets one more run to fix them. A repo that declares none runs none here.
  3. The reviewer reads the change (see The local reviewer).
  4. The daemon commits the change as the App’s bot, with you as Co-authored-by, and pushes the branch with a token MergeLoop mints for that one repo and that build. It never pushes over the branch if it changed on GitHub while the build ran: the build is stuck instead, saying so.
  5. MergeLoop’s App opens the PR: not a draft, labeled with the repo’s label, assigned to you, its body starting with Closes #<issue>.
  6. The daemon lands it, as below.

A build holds a slot from its claim until its PR is open, and again while an agent works a need on the PR. A PR that waits holds none.

Once its PR is open, the daemon is the PR’s author in the land loop (next_need), as mergeloop [PR] is for an agent. Review threads, and changes a required reviewer asked for, are worked by the agent in a fresh worktree on the PR’s branch: the agent changes files only, and the daemon runs verify, commits as the App’s bot with you as Co-authored-by, pushes, then posts the agent’s replies in the threads, each naming the pushed commit, and resolves the threads the agent named. When GitHub refuses a reply, a resolve or the read of the threads, the daemon tries again, twice more, without running the agent again or posting a reply twice. After a run that pushed, the daemon waits for MergeLoop to say what the PR needs next. After a run that pushed nothing, it asks again at once: a need still as it was was not settled by the run, and the next run is told so, with the threads still open, since a reply alone closes none. A PR that waits, on the queue or on a human (an approval, a draft, a PR taken out of the queue), runs no agent, and the daemon asks how it stands as often as it heartbeats. An ejected PR is queued again once. When MergeLoop cannot answer for now (it is unreachable, or answers 5xx), the daemon says so and asks again after a pause; only MergeLoop’s refusals end a build. A repo renamed while its PR lands is no refusal: the daemon reads the build’s task again and goes on under the new name.

The daemon names itself once, in daemon/id in its folder, and holds only the builds it claimed: another daemon of yours, on this machine or another, takes one only once it is given back or goes 30 minutes unheard, as anyone’s would.

The config file

mergeloop daemon --help lists the settings. They live in ~/.mergeloop/daemon.toml, or the file --config FILE names; without the file, the defaults hold. An unknown key is an error.

slots = 1                          # builds at once, at least 1
workspace = "~/.mergeloop/daemon"  # the daemon's own folder, new or empty at first: absolute, or ~/...
access = "workspace"               # or "full": see "What an agent may do on your machine"
# deny_read = ["~/.ssh", ...]      # what a build may not read in workspace access: replaces the default list

[builder]
agent = "claude"                   # or "codex": the flags it gets, and how its output reads
command = "claude"                 # default: the agent's name; a wrapper that takes its flags works, such as "mclaude"
# model = "..."                    # default: the CLI's own
# effort = "..."                   # default: the CLI's own
args = []                          # more arguments for every run, after MergeLoop's
timeout_minutes = 60               # the longest one run may take, at least 1

[reviewer]
enabled = true                     # false: no local review
# agent = "codex"                  # default: the other agent when its CLI is on PATH, else (or when command is set) the builder's
# command = "codex"                # default: the agent's name, or, for the builder's own agent, the builder's command and args
# model = "..."                    # its own, not the builder's; default: the CLI's own
# effort = "..."                   # its own; default: the CLI's own
# args = []                        # default: none, or the builder's with the builder's command
timeout_minutes = 60               # the longest one review may take, at least 1

The default deny_read is your MergeLoop session (~/.mergeloop/session) and the places credentials live in a home folder: ~/.ssh, ~/.aws, ~/.gnupg, ~/.netrc, ~/.git-credentials, ~/.config/gh, ~/.config/gcloud, ~/.azure, ~/.docker/config.json, ~/.kube, ~/.npmrc, ~/.cargo/credentials, ~/.cargo/credentials.toml, ~/.pypirc, ~/.gem/credentials, ~/.codex/auth.json, ~/.claude/.credentials.json. A path that holds the daemon’s folder, or lies in it, is an error. The agent CLIs read their own login themselves, outside their sandboxes, so they keep working.

The local reviewer

Between verify and the push, a reviewer reads the change against the issue: a fresh session of the other agent CLI (Codex for a Claude builder, Claude for a Codex one) when it is on your PATH, else of the builder’s own. It answers with findings, each at a file and line, or with none. Findings go back to the builder as a new run in the same worktree, verify runs again, and the reviewer reads the change again: at most 3 reviews. Findings left after the third make the build stuck, with them, and nothing is pushed; so does a reviewer that does not answer with its findings.

The PR body’s Local review section says who reviewed the change and in how many rounds, or that the local review was turned off on the machine that built it. A change made later for a need on the PR is not reviewed on the machine: MergeLoop’s own review reads it on the PR.

The reviewer runs with the builder’s access, read denials and environment, and no token of any kind, in a folder of its own (reviews/<build>/, outside the build’s): in workspace access it may write only there and in its CLI’s temp folder, so it reads the build’s worktree and cannot change it. In full access nothing confines it, and what stands is the daemon’s check, after every review, that the worktree still holds just the commit it reviewed: a build whose reviewer changed a tracked file, added an unignored one or committed is stuck, with nothing pushed. Writes to ignored files, or outside the worktree, are not caught.

Who the agent acts as

An agent and what it runs never act as you on GitHub or MergeLoop: a reply or a resolved thread from your own login would count as a human’s answer to MergeLoop’s review. Every run loses GH_TOKEN, GITHUB_TOKEN, MERGELOOP_TOKEN, MERGELOOP_URL, SSH_AUTH_SOCK and the like from your environment; gh gets an empty config folder in the build’s folder (GH_CONFIG_DIR), and git no credential helper and no prompt.

The workspace folder, and how it is cleaned

The daemon’s folder, ~/.mergeloop/daemon by default, must be its own. The daemon makes it its own when it first starts there, if the folder is missing or empty, by writing its name in daemon/id. It refuses to start in a folder that has other things in it and no daemon/id, and touches nothing there: give it a new folder instead. It holds:

The agent and each verify command run in a process group of their own, and whatever they leave running is stopped when their run ends; a process that leaves its group (setsid) is not found. A build’s folders and local branch are removed when the build ends, however it ends, once its processes are gone. A PR’s need gets a worktree only while its agent works, and loses it once the change is pushed: a PR that waits has nothing on disk but its transcripts. On start, the daemon stops what a daemon killed mid-build left running, removes whatever a crash left of builds, gives back the builds without a PR that it still holds, and lands again those with one, once MergeLoop has finished labeling and assigning their PR. It removes only what it knows as a leftover of its own, saying so in one line: a build’s or a reviewer’s folder of a build it does not hold, and a clone under repos/<owner>/<name>.git that is broken, such as one a crash left before it had its origin, which is made again when a build next needs it. It also removes a renamed repo’s clone that no build uses, and a repos/<owner>/<name>.git.gone, which is such a clone a crash left half removed. Anything else of another shape it leaves, saying so. It follows no symlink in its folder: it never makes one there, so a symlink where it keeps a folder of its own stops the start, with a message naming it, and nothing it points at is touched. A lock, a name or a record of process groups that it cannot read stops the start too, naming the path: stopping is safe, deleting is not.

How a build is confined

In workspace access, the daemon passes each CLI its own confinement:

The daemon’s own git on a build names the worktree’s git dir rather than following its .git, runs no hooks, and in workspace access runs under the same read denials, so nothing a build leaves runs as the daemon. It commits a build’s worktree only while it is the folder the daemon made: a build that puts a link or another folder in its place is stuck, and nothing is pushed.

How a build ends

Whose PR a built PR is

GitHub has the App’s bot as the author of a built PR. Everywhere MergeLoop asks whose PR it is, it is the PR of the developer whose daemon holds its build at that moment: the seat it takes when it joins a private repo’s queue, and the name it is kept under in the history, the people view and the queue’s events. A developer has one seat whether their PRs are built or their own. When a stale build is taken over, the seat already taken when the PR joined stays; the next count made, such as its leaving the queue, is the new holder’s. A seat is kept by GitHub login, as for every PR, and the daemon’s login is the one from its sign-in: a developer who renames their GitHub account, even only its capitalization, runs mergeloop login again, or their built PRs take a seat under the old name beside the one their own PRs take.

Dark merges

A dark merge is one that no human saw. The build lane does not decide this; two gates do, both outside the daemon: MergeLoop’s review, with its confidence bars and the kinds it always asks a human about, and GitHub’s rules for the branch, which the repo’s maintainers set. What must never merge dark is a human decision, made as a required approval.

The App’s bot is the author of every built PR, so the developer whose daemon built it is not: they can approve it, and MergeLoop counts their answer to a question its review asks. GitHub does not let an author approve its own PR, so MergeLoop never approves a PR it built. How dark a built PR gets depends on the repo’s rules:

How the repo is set upAn ordinary changeA path that must never merge dark
Rules by path. No approval is needed in general; sensitive paths need their code owner.Dark. It merges once MergeLoop’s review lets it on.A human. The code owner approves; that can be the developer, if they are one.
Every PR needs one approval. The common default.One click. The developer approves their daemon’s PR. Never dark.A human. The code owner approves.

A PR a person opens can merge dark under “every PR needs one approval”, since MergeLoop approves it once its review passes; a built PR cannot. Letting MergeLoop bypass that rule for built PRs, with the sensitive paths in a second ruleset with no bypass, is not built: GitHub’s documentation does not say whether that second ruleset still holds against the bypass, or how MergeLoop could tell before it merges. docs/build-bypass.md says what it does say, and the check on a scratch repo that would settle it. Making the App a bypass actor changes nothing today: MergeLoop never asks GitHub to use a bypass.

Docs