mergetrain

Parallel agents need a serial integration spine.

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

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.

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

... View full README on GitHub