How it works
Mergehand has two parts: the server you use in the browser, and a runner on your own machine where the agent works.
Two parts
Mergehand server
The web application at app.mergehand.com: projects, members, integrations, plans waiting for approval, reports and merge requests. It talks to your code host and tracker, and it is the only part that pushes branches and opens merge requests – after your approval.
Runner on your machine
A small service in Docker that you install on your computer or your own server. It keeps clones of your repositories and starts a fresh, isolated container for every run of the agent. The runner connects out to the server, so no inbound port needs to be opened.
What stays with you
- Your repositories. They are cloned, built and tested on the runner, in your environment.
- Your AI sign-in. You sign in to the AI agent on the runner, with the agent itself, or you give the runner a token or an API key from your AI provider. The server never receives it and has no field to enter it.
- Your bill for the model. You pay your AI provider directly through your AI subscription or API key. Mergehand does not resell, pay for or bill model usage.
Mergehand runs the AI agent as its provider ships it. Each member uses their own runner with their own AI sign-in – one shared account for the whole team is not how it works.
A task, step by step
- You start a task
Enter the issue ID. The server downloads the issue, comments and attachments and hands them to the runner. - Analysis and plan
The agent reads the code and writes a plan with numbered acceptance criteria. Questions come to you. - Plan approval
You approve with a click. No code is written before that. - Implementation
The agent works in a separate working copy and runs the checks your repository defines – on the changed files. - Review
A fresh agent, which did not write the code, reviews it. Findings go back to be fixed. - Testing
Another fresh agent tests each acceptance criterion and reports every check as passed, failed, not applicable or not run. - Result approval
You read the report, open findings and checks that did not run. You approve, or send it back. - Push and merge request
The server checks the branch – it builds on what is already on the remote, and the commits are yours – then pushes and opens a draft merge request.
On GitHub and Bitbucket, the merge request is a pull request.
When your runner is off
Work waits in the queue and the application shows whose runner is not connected. When the runner connects again, the queued work starts.
What the runner needs
- Linux (x86_64 or ARM64) with Docker Engine 26 or newer and Docker Compose 2.24 or newer. Windows works through WSL2 and Docker Desktop.
- macOS on Apple Silicon or Intel with Docker Desktop, with at least 8 GB of memory for its virtual machine. The images are native for both. Mac support is new – if you try it, let us know how it went.
- About 4 vCPU and 8 GB RAM for one run at a time; more for parallel runs.
- An AI subscription or an API key from your AI provider.
After you sign up, the app walks you through installing the runner.