{
"markdown": "# mergetrain\n\n\n\n[](https://github.com/yongjip/mergetrain/actions/workflows/ci.yml)\n[](https://pypi.org/project/mergetrain/)\n[](https://pypi.org/project/mergetrain/)\n[](https://github.com/yongjip/mergetrain/blob/main/LICENSE)\n\n**Safely integrate committed branches from parallel coding agents.**\n\nmergetrain is a local-first deploy train for coding-agent worktrees. Agents\ncommit and enqueue their branches; one runner assembles them in order, tests the\ncombined tree, and atomically updates your Git refs only after explicit approval.\nIt is intentionally optimized as an owner-operated local utility, not a hosted\nteam platform.\n\nThere is no mergetrain account, hosted control plane, OAuth app, or product\ntelemetry. Queue and runner state stay on your machine; only your configured Git\nremote and trusted gate or verification commands may contact external services.\n\n## The problem\n\nWorktrees let several agents edit one repository without sharing a checkout.\nThey do not decide landing order, test the combined result, prevent push races,\nor tell you what happened if a laptop dies mid-push.\n\nWithout an integration boundary, the human becomes that boundary: rebase every\nfinished branch, rerun gates after each merge, resolve cross-branch failures,\nand decide which session may push. The parallel coding gain disappears at the\nlast mile.\n\n
\n \n
\n\nmergetrain makes that last mile a durable protocol:\n\n```text\nagent branches → FIFO queue → isolated integration worktree → combined gates\n → explicit approval → one atomic push → post-push verification\n```\n\n## Who should use it?\n\nUse mergetrain when:\n\n- multiple coding agents finish branches in the same repository throughout the\n day;\n- agents work in Git worktrees and should enqueue rather than push deploy refs;\n- the combined result must pass local tests before it lands;\n- you want unattended processing only for explicitly pre-approved jobs; or\n- one local hub should show queues and runners across several repositories.\n\nIt is harness-agnostic: Codex, Claude Code, agy, scripts, and humans all use the\nsame CLI and JSON contract.\n\n## Who should not use it?\n\nYou probably do not need mergetrain when:\n\n- one person or agent lands one branch at a time;\n- every change already goes through a PR and your forge-native merge queue;\n- you need a hosted review UI, organization-wide permission system, or remote\n runner service; or\n- you are looking for a general job queue, CI provider, or deployment platform.\n\nFor PR-first teams, use GitHub Merge Queue or GitLab Merge Trains. mergetrain is\nfor local-agent, worktree-first integration, with or before a PR.\n\n## Enforcement boundary\n\nLease tokens fence concurrent and stale **mergetrain runners**. They do not\nintercept an arbitrary `git push` from a task agent that has shell access and an\nintegration-branch credential. To make “one runner owns the push” an enforced\nproperty rather than a protocol assumption, use this topology:\n\n```text\ntask agents: commit + exact-SHA enqueue; no integration push credential\nrunner: separate deploy identity\nremote: protected integration branch; runner or reviewed PR path only\n```\n\nWithout credential separation and remote protection, mergetrain still provides\nsafe train assembly and recovery semantics, but it cannot prevent a participant\nfrom bypassing the queue. See the [security boundary](https://github.com/yongjip/mergetrain/blob/main/docs/security.md#runner-and-task-agent-credentials).\n\n## See it in 60 seconds\n\n```sh\nuvx mergetrain demo\n```\n\nThe demo creates a disposable repository and local bare remote, then runs four\nreal branches through FIFO merge, a combined-only gate failure, conflict\nattribution, and deployment of the compatible train. Use `--keep` to inspect the\nresult afterward.\n\n
\n \n
\n\n## Install and first run\n\n```sh\n# Install the machine-level CLI\nuv tool install mergetrain # or: pipx install mergetrain\n# macOS: brew install yongjip/tap/mergetrain\n\n# Codex: add the Git marketplace, then install the native skill + pinned MCP server\ncodex plugin marketplace add yongjip/mergetrain --ref main\ncodex plugin add mergetrain@mergetrain\n\n# agy: install the native skill + pinned MCP server\nagy plugin install https://github.com/yongjip/mergetrain\n\ncd /path/to/your/repo\n\n# Write .mergetrain.yaml plus agent instructions\nmergetrain init --project my-app --write\n\n# After an agent commits its task branch\nmergetrain enqueue \\\n --task \"add health check\" \\\n --branch agent/health\n\n# Read state and deploy end to end\nmergetrain status\nmergetrain deploy\n```\n\nFor long-running gates, run `mergetrain validate` earlier; it never pushes and\nleaves one exact train Ready for the later `deploy` confirmation.\n\n`deploy` names the configured atomic Git ref update; it does not imply an App\nStore, Kubernetes, or other provider release.\n\n`mergetrain init` also writes agent-facing instructions. The essential rule is\nsimple: agents commit and enqueue; one runner owns merge → test → push → verify.\nUnattended daemons process only jobs that a human explicitly enqueued with\n`--auto`. For manual jobs, `daemon --validate-only` can run merge and gates in\nthe background, but it pauses at the validated-train approval boundary and\nnever pushes.\n\nSee the [quickstart](https://github.com/yongjip/mergetrain/blob/main/docs/quickstart.md)\nfor configuration, dashboard, daemon, and multi-repository Hub setup.\n\n## Why not just worktrees and `git merge`?\n\nWorktrees solve **parallel editing**. mergetrain solves **serialized\nintegration**.\n\n| Integration concern | Worktrees + manual merge | mergetrain |\n|---|---|---|\n| Landing order | A person or agent decides repeatedly | Durable FIFO queue |\n| Combined validation | Rerun manually after each merge | Gates run over the exact assembled train |\n| Cross-branch failure | Diagnose by hand | Isolation runs identify the conflicting pair |\n| Push ownership | Every session can race the ref | One lease-fenced runner owns the push |\n| Approval | Shell convention | Explicit validate/deploy intent; `--auto` is opt-in |\n| Crash recovery | Infer from local logs | Reconcile SQLite evidence against remote refs |\n\nPlain worktrees remain the execution lanes. mergetrain is the spine that joins\ntheir results without turning the operator into a merge coordinator.\n\n## Why not GitHub or GitLab merge queues?\n\nThey solve a related problem for a different operating model.\n\n| | Forge-native queue | mergetrain |\n|---|---|---|\n| Primary unit | Pull/merge request | Committed local task branch |\n| Validation | Forge merge group + remote CI | Local assembled train + shell gates |\n| Review | Built-in conversation and approvals | No code-review UI |\n| Infrastructure | Forge integration and hosted services | Local SQLite, Git worktrees, any Git remote |\n| Best fit | PR-first teams and distributed review | High-throughput local agent integration |\n\nThe models can coexist: push a validated train to a review branch and open one\nPR, or reserve individual PRs for changes that need discussion. The\n[PR workflow guide](https://github.com/yongjip/mergetrain/blob/main/docs/pr-workflows.md)\ncovers direct, one-PR, split-PR, and validation-only patterns.\n\n## Core safety guarantees\n\n- **Exact train identity.** Approval names the task HEADs and integration base;\n changed branches or a moved base cannot silently reuse that approval.\n- **Combined gates before push.** A green branch is not enough. The assembled\n train passes the configured gates, or nothing lands.\n- **One fenced mergetrain owner.** SQLite claims and lease tokens prevent\n concurrent or stale mergetrain runners from mutating the same train; remote\n enforcement additionally requires the credential topology above.\n- **Atomic remote update.** Payload refs and a permanent\n `refs/mergetrain/deploys/` recovery ref update together.\n- **Remote-truth recovery.** Write-ahead markers and pinned commits let\n `reconcile` determine whether a killed push landed, without replaying\n a successful deploy or calling a missing one shipped.\n- **Explicit automation.** A bare run never deploys. Daemons touch only\n pre-approved `--auto` jobs whose destination and gate/reuse/verify policy\n still match, and MCP deploy still requires attributable human confirmation.\n- **One state entry point.** `status` projects internal detail into Waiting,\n Running, Ready, Attention, and Done, and returns the next safe command.\n `inspect` supplies job-level evidence only when it is needed.\n\nQueue state, locking, train assembly, and gates stay local. Your configured Git\nremote and post-push verification may still use external services. Gate and\nverify commands are trusted code; review the\n[security boundary](https://github.com/yongjip/mergetrain/blob/main/docs/security.md)\nbefore enabling unattended jobs.\n\nThese guarantees are exercised on macOS and Linux across Python 3.10–3.14 and\non Windows, including real-Git fault injection around `git push --atomic`. A\ndedicated soak repository completed 20 landed trains at a 100% land rate,\nincluding planned conflict recovery and a real killed-push reconciliation whose\nverdict matched the remote. See the\n[soak evidence](https://github.com/yongjip/mergetrain/blob/main/docs/soak.md),\nthen use `mergetrain stats --json` to inspect evidence from your own queue.\n\n## Go deeper\n\n- Start: [Quickstart](https://github.com/yongjip/mergetrain/blob/main/docs/quickstart.md) ·\n [Install](https://github.com/yongjip/mergetrain/blob/main/docs/install.md) ·\n [CLI](https://github.com/yongjip/mergetrain/blob/main/docs/cli.md) ·\n [Config](https://github.com/yongjip/mergetrain/blob/main/docs/config.md)\n- Understand: [Design and architecture](https://github.com/yongjip/mergetrain/blob/main/docs/design.md) ·\n [Machine contract](https://github.com/yongjip/mergetrain/blob/main/docs/contract.md) ·\n [PR workflow comparison](https://github.com/yongjip/mergetrain/blob/main/docs/pr-workflows.md)\n- Operate: [Efficient operation](https://github.com/yongjip/mergetrain/blob/main/docs/best-practices.md) ·\n [Failure modes and recovery](https://github.com/yongjip/mergetrain/blob/main/docs/failure-modes.md) ·\n [Daemon](https://github.com/yongjip/mergetrain/blob/main/docs/daemon.md) ·\n [Multi-repo Hub](https://github.com/yongjip/mergetrain/blob/main/docs/hub.md)\n- Trust and extend: [Security](https://github.com/yongjip/mergetrain/blob/main/docs/security.md) ·\n [Agent contract](https://github.com/yongjip/mergetrain/blob/main/docs/agent-contract.md) ·\n [Agent adoption benchmark](https://github.com/yongjip/mergetrain/blob/main/docs/agent-adoption-benchmark.md) ·\n [Product-name-free discovery benchmark](https://github.com/yongjip/mergetrain/blob/main/benchmarks/discovery/README.md) ·\n [Local multi-agent benchmark](https://github.com/yongjip/mergetrain/blob/main/benchmarks/multi_agent_integration/README.md) ·\n [MCP server](https://github.com/yongjip/mergetrain/blob/main/docs/mcp.md) ·\n [Adapter pattern](https://github.com/yongjip/mergetrain/blob/main/docs/adapter-pattern.md) ·\n [Product scope](https://github.com/yongjip/mergetrain/blob/main/docs/product-scope.md)\n\n## Stable interface\n\nThe normal CLI is deliberately limited to six verbs:\n\n```text\ninit status enqueue validate deploy inspect\n```\n\nVersion 3 is the long-lived product grammar. There is no planned v4: new\ncapabilities must fit these verbs or stay in advanced operator surfaces, and\nthe v3 JSON and MCP contracts evolve additively. See the\n[compatibility policy](https://github.com/yongjip/mergetrain/blob/main/docs/contract.md#long-lived-v3-compatibility-policy).\n\nThe latest published release is shown by the PyPI badge above.\nIssues and operating reports are welcome on\n[GitHub](https://github.com/yongjip/mergetrain/issues).\n\n## License\n\nReleased under the [MIT License](https://github.com/yongjip/mergetrain/blob/main/LICENSE).\n",
"bytes": 12608,
"sha": "6fbc1ef41c5fa69674fb683061772823719ee9411db0bb840a4c5521fb02fa0c",
"repo_slug": "yongjip/mergetrain",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_yongjip_mergetrain_36a5a6d3/readme"
}
![\"Three](\"https://raw.githubusercontent.com/yongjip/mergetrain/main/docs/images/mergetrain-explainer.gif\"\n)
\n![\"mergetrain's](\"https://raw.githubusercontent.com/yongjip/mergetrain/main/docs/images/demo.gif\"\n)
\n