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" | |
|---|---|---|
| Writes | Only 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 |
| Reads | Anything you can read, except the deny_read paths: by default your MergeLoop session and the places credentials live in a home folder | Anything you can read |
| Prompts | None: the agent works without asking | None |
| macOS | The agent CLI’s own sandbox (Claude Code’s, Codex’s permission profile), and sandbox-exec for the verify commands. Checked on this platform. | |
| Linux | The 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. | |
| Elsewhere | Refused when the daemon starts |
What nothing stops, in either mode:
- Reads outside
deny_read. Your source, your dotfiles and anything else you can read, the agent can read. - The network. It is open, so what the agent reads it can send.
- The macOS keychain. An agent can ask it, through
security, for what it holds, as your own programs can; agit -c credential.helper=osxkeychain pushof a ref that exists is a network call no sandbox sees. - Claude Code’s temp folder. Its shell may always write
/tmp/claude-<uid>, which every build shares: it does not run without it. fullaccess. It lifts the confinement and the read denials alike (--permission-mode bypassPermissions,--dangerously-bypass-approvals-and-sandbox). Tools that write outside the build’s folder, such as a package manager’s cache in your home folder, fail underworkspaceand need it.
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
- 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. - Put the repo’s label (its
labelsetting,mergeloopby 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 theissuesevent 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. - On each machine that builds, install the
mergeloopcommand and runmergeloop loginonce. Install the builder’s agent CLI (Claude Code by default) and sign in to it, asmergeloop logindoes 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 yourPATH(Codex for a Claude builder), else the builder’s own. A CLI that is on yourPATHbut not signed in must be signed in, or the reviewer set in[reviewer](agent,command), or turned off (enabled = false). Then runmergeloop 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:
- In its own clone of the repo and a fresh worktree, on the branch
mergeloop/build-<issue>, the builder agent builds the issue. - The repo’s
verifycommands, 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. - The reviewer reads the change (see The local reviewer).
- 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. - MergeLoop’s App opens the PR: not a draft, labeled with the repo’s label, assigned to you, its body starting with
Closes #<issue>. - 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 builder, the reviewer and every
verifycommand get no token. - An agent working a need on the PR gets a token for the build’s repo that only reads it and its PRs (
contents: read,pull_requests: read), asGH_TOKEN,GITHUB_TOKENandMERGELOOP_TOKEN, soghandmergeloop callread as the App’s bot. It reads what anyone who can comment on the PR wrote, so it holds nothing that can write. - The token that pushes (
contents: write,pull_requests: write, for that one repo, for GitHub’s hour) stays in the daemon, for its own git and its replies and resolves. The daemon asks for it withmint_build_tokenand thepushscope; MergeLoop mints it only while you hold the build and GitHub says, asked afresh, that you may push. It does not carry GitHub’sworkflowspermission, so a build cannot change the files under.github/workflows: GitHub refuses the push, and the build is stuck with that refusal as its reason. An issue that changes CI is one for a person.
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:
daemon/: its lock (a second daemon on the same folder refuses to start), its name (id), and the process groups its builds run.repos/<owner>/<name>.git: its own clone of each repo it builds in. It never touches your checkouts. When the daemon learns that a repo was renamed, as a PR lands, the clone under the old name is marked (mergeloop-renamedin it) and removed once no build’s worktree is in it: at once, or when the last such build ends. Builds go on under the new name, in a clone of that name. A repo renamed while no build of it is landing leaves its old clone, which you may remove while the daemon is stopped.builds/<build>/: a build’s folder, its worktreetree/on its local branch, and itstmp/.reviews/<build>/: the reviewer’s folder, made empty for each review.transcripts/<build>/: what the agents printed, kept 7 days after last written.
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:
- Claude Code:
--setting-sources user(a repo’s.claude/settings, which a build can write, never loosen it),--permission-mode acceptEdits --add-dir <build folder>, and--settingsthat turn on its sandbox (refusing to start without one, with no retry outside it, network open) withfilesystem.denyRead, aReadallow rule andReaddeny rules for its file tools (so they read what its shell may), andpermissions.blockWritesOutsideWorkingDirectories. - Codex:
--skip-git-repo-check(a reviewer’s folder is no git repo),--ignore-user-config(yourconfig.tomlis not read, as asandbox_modein it would replace what follows; your login still is), and a permission profile in-c: read everything, write the build’s folder,denyeachdeny_readpath, network on, no approvals. verifycommands:sandbox-execon macOS,bwrapon Linux, writing only the build’s folder and reading nodeny_readpath, nor a symlink to one.
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
- Merged. The PR merged, by the queue or outside it. The build shows as merged until its issue closes, as the PR’s
Closes #<issue>does. - Stuck. The agent gave up,
verifystill failed after its fix, the reviewer still had findings after 3 rounds, the PR was ejected a second time or still needed its author after 10 runs of the agent, GitHub kept refusing the daemon’s answer, a person closed the PR without merging it, or anything else went wrong. The daemon says why on the issue, and the Builds page shows it in full. To try again, take the label off the issue and put it back: a stuck build with an open PR goes back to landing it, and one whose PR was closed is built anew over the old branch. - Given back. Ctrl-C gives back the builds without a PR: they are tasks again at once. It keeps those with one, which the daemon lands again when started; another daemon takes one over once it goes 30 minutes unheard. A build is given back too when GitHub says you may no longer push.
- Dropped. The issue was closed or lost its label before the build had a PR. A build with a PR is never dropped this way: closing its issue is what merging it does.
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 up | An ordinary change | A 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
- Get started with MergeLoop
Sign in with GitHub, install the App, merge the setup PR, add a model key, and label a pull request to queue it.
- How the merge queue works
What a queued PR needs, the agent that resolves conflicts and fixes failed checks, automatic review, branches, batches, stacks and PRs from forks.
- Configuration: .mergeloop/mergeloop.yml
Every setting in a repo's .mergeloop/mergeloop.yml: the label, batch size, the agent's model, verify commands, CI fixes, extra branches and review bars.
- Pricing
MergeLoop is free on public repos. Private repos cost $15 a seat a month after a 14-day trial with no card. Self-hosting is free.
- MCP server and API
Let Claude Code, Codex or Cursor queue and review PRs through MergeLoop's MCP server, or read a PR's queue state from the JSON API.
- Self-host MergeLoop
Run the open-source MergeLoop yourself with Docker Compose, configure it, bring your own GitHub App, and isolate its jobs in gVisor sandboxes.