Mergetrain

mergetrain

Safely integrate committed branches from parallel coding agents.

mergetrain is a local merge queue for parallel LLM agents. These coding agents use large language models and work in Git worktrees. mergetrain runs on your machine. A train is a group of queued task branches. A gate is a configured test or check. Each agent commits and enqueues its branch. One runner merges branches in enqueue order and runs gates on the combined result. It updates your Git refs atomically only after explicit approval.

mergetrain is designed for one operator managing local repositories.

There is no mergetrain account, hosted control plane, OAuth app, or product telemetry. Queue and runner state stay on your machine. Only your configured Git remote and trusted gate or verification commands may contact external services.

Keep building through the fix

Default batch mode: passing work lands first. Work that needs a fix returns to its agent. Passing work can land while the repair continues.

Keep building during checks. Agents start their next task while mergetrain checks earlier work. This 14-second loop keeps the same four agents in view.

Agents can keep building in both modes. In ordered mode, an unresolved earlier submission holds later landings. Compare the two modes.

Pause or replay the demo · View the still image · Reproduce the continuous workflow

How this demo was made

This illustration follows recorded CLI results. The four lanes represent agent roles; letters identify work, not queue job IDs. The capture scripts agent-authored changes and operator approvals in a disposable local repository and bare remote. It does not launch an AI service.

Two fixture gate waits make the overlaps reproducible: E and F are committed during A and B validation, then G and H drafts start during E and F validation. All three deployments retain approval and the default recheck. A fresh clone of the final remote passes six tests.

G and H then refresh onto that result without losing their edits. I and J start there too. These four drafts remain unsubmitted. Your agents or operator create, fix, refresh and resubmit work; mergetrain checks and integrates it. The 14-second animation repeats this recorded window with condensed timing.

The problem

Worktrees let several agents edit one repository without sharing a checkout. They do not decide landing order, test the combined result, prevent push races, or tell you what happened if a laptop dies mid-push.

Without a shared integration workflow, the operator chooses branch order and resolves cross-branch failures. The operator also reruns tests and controls pushes. Repeating these actions can slow parallel work.

mergetrain records this workflow in a durable local queue:

agent branches → local queue → isolated integration worktree → combined gates

→ explicit approval → one atomic push → post-push verification

Who should use it?

Use mergetrain when:

• multiple coding agents finish branches in the same repository throughout the day;
• agents work in Git worktrees and should enqueue rather than push deploy refs;
• the combined result must pass local tests before it lands;
• you want unattended processing only for explicitly pre-approved jobs; or
• one local hub should show queues and runners across several repositories.

It is harness-agnostic: Codex, Claude Code, agy, scripts, and humans all use the same CLI and JSON contract.

Running several Claude Code or Codex sessions on one laptop? The one-laptop guide covers worktrees, unattended landing, heavy gates, sleep and quiet periods, a push guard, and outcome reports, each tested in disposable repositories.

Who should not use it?

You probably do not need mergetrain when:

• one person or agent lands one branch at a time;
• every change already goes through a PR and your forge-native merge queue;
• you need a hosted review UI, organization-wide permission system, or remote runner service; or
• you are looking for a general job queue, CI provider, or deployment platform.

For PR-first teams, use GitHub Merge Queue or GitLab Merge Trains. mergetrain is for local-agent, worktree-first integration, with or before a PR.

Batch by default; ordered when needed

Start with `batch`, the default. It suits independent work from parallel agents. The runner combines the queued work available when it starts; it does not wait for every agent to finish. Compatible work can land while an agent repairs a failed submission.

Use ordered when each change needs its own landing and the original submission order must survive a failure and retry.

Both modes let agents start their next task after handoff. Both keep deploy approval and the default pre-push recheck. Ordered processing can run checks more often because each submission lands separately. Queue order starts at submission, not when an agent starts work, and does not express code dependencies. Order ends at a successful Git landing. Post-push verification warnings remain visible while later work proceeds; an uncertain push still requires reconciliation.

Availability: ordered is available in 3.6.0 and newer. Keep the default batch for ordinary parallel agent work. See the agent work examples, configuration, and upgrade procedure.

Enforcement boundary

Lease tokens fence concurrent and stale mergetrain runners. They do not intercept an arbitrary git push from a task agent that has shell access and an integration-branch credential. To make “one runner owns the push” an enforced property rather than a protocol assumption, use this topology:

task agents: commit + exact-SHA enqueue; no integration push credential

runner: separate deploy identity remote: protected integration branch; runner or reviewed PR path only

Without credential separation and remote protection, mergetrain still provides safe train assembly and recovery semantics, but it cannot prevent a participant from bypassing the queue. See the security boundary.

Run the real demo

uvx mergetrain demo

The demo creates a disposable repository and local bare remote, then runs four real branches through merges in enqueue order, a combined-only gate failure, conflict attribution, and deployment of the compatible train. Use --keep to inspect the result afterward. Add --brief --pause to read each step before continuing. The extended workflow recording adds repair, work committed during validation, the next batch, and three verified local deployments.

Full CLI recording

Install and first run

# Install the machine-level CLI

uv tool install mergetrain # or: pipx install mergetrain

macOS: brew install yongjip/tap/mergetrain

Codex: add the Git marketplace, then install the native skill + pinned MCP server

codex plugin marketplace add yongjip/mergetrain --ref main codex plugin add mergetrain@mergetrain

agy: install the native skill + pinned MCP server

agy plugin install https://github.com/yongjip/mergetrain

For VS Code / GitHub Copilot or direct MCP setup, see the MCP installation and deployment-confirmation guide.

Initialize the repository:

cd /path/to/your/repo

mergetrain init --project my-app --write

Add at least one project gate to .mergetrain.yaml. A new configuration has gates: [], so it runs no project tests. For a Python project that uses pytest:

gates:

• name: tests run: python -B -m pytest -q -p no:cacheprovider

Use test commands for your project. Gates must leave the assembled checkout unchanged. init also creates AGENTS.mergetrain.md and CLAUDE.mergetrain.md. Link them from your existing AGENTS.md or CLAUDE.md. Commit and land the configuration and instructions through your normal integration path before creating task worktrees.

After the task agent commits a clean branch in its own worktree:

mergetrain status --json

mergetrain enqueue \ --task "add health check" \ --branch agent/health

The task agent stops after enqueueing. From the operator checkout, run these commands when validation and deployment are authorized:

mergetrain status

mergetrain deploy

For long-running gates, run mergetrain validate earlier; it never pushes and leaves one exact train Ready for the later deploy confirmation.

deploy names the configured atomic Git ref update; it does not imply an App Store, Kubernetes, or other provider release.

Agents commit and enqueue. One runner owns merge → test → push → verify. Unattended daemons process only jobs that a human explicitly enqueued with --auto. For manual jobs, daemon --validate-only can run merge and gates in the background, but it pauses at the validated-train approval boundary and never pushes.

See the quickstart for configuration, daemon, and multi-repository Hub setup.

Integrating parallel Claude Code sessions and Codex worktrees

Use a Git worktree merge queue when parallel Claude Code sessions or parallel Codex worktrees produce committed branches in the same repository. The plugin install guide connects either client to the queue. Task agents commit, enqueue, and stop. A separately authorized runner tests the combined branches and handles the push.

For Orca-managed worktrees, see the Orca setup and queue guide for tested terminal commands, shared queue behavior, validation, and repair. The Orca agent guide adds native Codex, Claude Code,