mergetrain

# mergetrain

<!-- mcp-name: io.github.yongjip/mergetrain -->

[![CI](https://github.com/yongjip/mergetrain/actions/workflows/ci.yml/badge.svg)](https://github.com/yongjip/mergetrain/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/mergetrain)](https://pypi.org/project/mergetrain/)
[![Python](https://img.shields.io/pypi/pyversions/mergetrain)](https://pypi.org/project/mergetrain/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/yongjip/mergetrain/blob/main/LICENSE)

**Parallel agents need a serial integration spine.**

Let agents code in parallel. Let one train prove and ship the result.

<p align="center">
  <img src="https://raw.githubusercontent.com/yongjip/mergetrain/main/docs/images/mergetrain-explainer.gif"
       alt="What happens when 3 AI agents push to main at once. Without a queue they collide and break main. With a merge train they enqueue, one runner assembles main + A + B + C, gates run once on the combination, and one atomic push keeps main green."
       width="720">
</p>

mergetrain is a local-first integration runtime for coding-agent worktrees.
Worktrees give each agent an independent lane, but the repository still has one
ordered history: without a coordinated landing boundary, parallel coding turns
back into manual rebases, merge races, and repeated test runs. mergetrain keeps
that missing integration spine on your machine. Coding agents commit and
enqueue; one local runner serializes their branches, validates the exact train,
and pushes only after explicit approval. No hosted merge-queue service or CI
provider is required.

![The mergetrain hub: every repo's queue, runner, and next safe action on one read-only board](https://raw.githubusercontent.com/yongjip/mergetrain/main/docs/images/hub-overview.png)

Four guarantees shape the design: an **exact validated train identity** (the
train you approved is the train that ships, byte for byte), a **lease-fenced
single runner** (two processes can never race a push), an **atomic multi-ref
push**, and **crash-safe, exactly-once deploys** (after any crash, recovery
reconciles the local queue against the *remote*, so a landed train is never
re-pushed and a lost one is never mislabeled as shipped).

> **Local-first, not local-only.** Queue state, locking, train assembly, and
> gates stay local. Configured Git remotes and post-deploy verification may
> still use external services.

> Status: current release (`v1.2.0`). The machine contract is frozen —
> additive-only within contract major 1 — and the real-repo soak gate is
> complete. Built to scratch my own itch first — published in case it scratches
> yours too.

---

## The problem

One repo, three coding-agent sessions running at once — Codex, Claude, whatever
— each in its own `git worktree` on its own branch: one adds a health check,
one refactors config loading, one fixes a flaky test. All three finish within
the same hour. Now what?

Without a queue, the ending is always one of these:

- **You become the merge coordinator.** Deciding landing order, rebasing each
  branch onto the last landing, rerunning the tests after every one — serially,
  by hand. The time you saved by running three agents in parallel is spent
  again integrating their results, and while you're integrating, you're not
  reviewing or directing.
- **Agents that push, race.** Two sessions push the same deploy branch within
  seconds: non-fast-forward rejects, a retry with `--force` that quietly
  clobbers the other session's landing, or an unreviewed merge combination
  shipping because whoever pushed last "won".
- **Green branches, red main.** Each branch passes its own tests, but two of
  them touched the same config loader in incompatible ways. No per-branch
  check can see that — only testing the *combined* result before it ships can.
- **Judgment calls land on an LLM.** Stale lock or live runner? Duplicate
  enqueue or a legitimate retry? Is unattended deploy actually approved for
  this job? These are exactly the calls you don't want an agent guessing at
  from fuzzy shell output.

### What mergetrain does about each

Each of those failure modes maps to a specific mechanism — this is the design,
not a feature list:

| Without a queue | With mergetrain |
|---|---|
| You order, rebase, and re-test every landing by hand | Agents **enqueue and stop**; one runner assembles the FIFO train in a throwaway worktree and lands it |
| Sessions race `git push`; a retry with `--force` clobbers | Agents never touch deploy refs; a **lease-fenced single runner** pushes atomically, exactly once |
| Green branches, red `main` | Gates run over the **exact combined train** before push; when a combination fails, the runner bisects it and names the conflicting pair (`conflict_with`) instead of shipping around the breakage |
| Stale locks, duplicate enqueues, "may I deploy?" become LLM guesses | Every state is JSON with an explicit `next_action`; deploys require explicit intent (`--deploy`), and unattended runs touch only pre-approved `--auto` jobs |
| The laptop dies mid-push | A write-ahead marker and pin ref let recovery ask the **remote** what landed — never re-pushed, never mislabeled |

That mapping is also the honest origin story: mergetrain exists because I was
running several coding-agent sessions on one repo and spending the hours they
saved me re-serializing their branches by hand. The queue was built to get
those hours back; the rest — validated train identity, crash recovery, the
multi-repo hub — followed from operating it every day. The parallelism you
paid for stays parallel.

### When to reach for it

- **Several agents, one project** — the core case, and the one it was built
  for: parallel worktree sessions on a single repo, landing their results all
  day without you serializing them by hand.
- **Unattended batches** — pre-approved `--auto` jobs land via the daemon
  while you're away; everything else waits for a human.
- **Agents across several repos** — the hub registers each repo and runs the
  same policy machine-wide, one repo's gates at a time.

One agent, one branch at a time? You don't need this — `git push` is fine.
And if your team is PR-first on a hosted forge with remote CI, use the
forge's native queue (see [alternatives](#alternatives--and-whats-different-here)).

### PR-first or mergetrain?

A fully parallel coding-agent workflow needs two things: **parallel execution
lanes** and a **serialized integration spine**. Worktrees provide the lanes;
mergetrain provides the spine. That integration layer is what preserves the
parallelism after several agents finish at nearly the same time.

A pull request is primarily a **human review unit**. A mergetrain job is an
**execution and integration unit** for a committed agent branch. Neither model
is universally better; the useful question is whether every agent branch needs
its own review conversation or whether several trusted branches should be
validated and landed as one train.

| Dimension | PR-first workflow | mergetrain |
|---|---|---|
| Strongest advantage | Human review, approvals, audit history, and distributed collaboration | Low-ceremony integration of many local agent branches |
| Validation | Usually per PR; a forge-native merge queue can add merge-group CI | Gates run over the exact assembled train before one atomic push |
| Latency and CI use | Each branch enters a remote PR/CI lifecycle | Local gates can validate a batch once; failures may trigger isolation runs |
| Platform model | Forge, webhooks, branch rules, and hosted CI | Local SQLite, Git worktrees, shell gates, and any Git remote |
| Main trade-off | Repeated PR ceremony and changing merge bases for small agent tasks | No code-review UI; you own the runner, credentials, and branch policy |

The two can coexist: use mergetrain for direct integration where that is the
policy, push a validated train to a review branch and open one PR, or reserve
individual PRs for changes that need human discussion. See the
[PR-first comparison and decision guide](https://github.com/yongjip/mergetrain/blob/main/docs/pr-workflows.md) for the full
pros, cons, and hybrid patterns.

Hosted merge queues (GitHub Merge Queue, GitLab Merge Trains, Mergify, Aviator, bors) solve a related problem, but they are PR-first, remote-CI-first, and platform-first. mergetrain is for the other workflow: **local-agent, worktree-first, deploy-branch-first.**

## How it works

```
  agent A ─┐
  agent B ─┼─▶  mergetrain queue (SQLite)  ─▶  one runner (lock)
  agent C ─┘                                      │
                                                  ▼
                          fresh integration worktree @ origin/main
                                merge A → B → C  (the train)
                                          │
                            gates (diff-check, tests, scans…)
                                          │
                              git push --atomic  →  configured refs
                                          │
                                  post-push verify hooks
```

Agents commit their work and **enqueue** a branch. They never push deploy refs themselves. A single **runner** (or unattended **daemon**) claims the queue, builds an isolated integration worktree on top of your integration branch, merges the queued branches in FIFO order, runs your gates once over the whole train, and only then pushes — atomically — to your deploy refs. Validation worktrees are disposable by default; path-sensitive build caches can opt into a runner-locked stable validation path while deploy worktrees remain disposable. Every important state is readable as JSON so an agent can follow the result instead of inferring it.

## Quickstart

<p align="center">
  <img src="https://raw.githubusercontent.com/yongjip/mergetrain/main/docs/images/demo.gif"
       alt="A terminal recording of mergetrain creating four agent branches, attributing a semantic conflict between two of the