mergetrain

Безопасно интегрируйте закоммиченные ветки параллельно работающих агентов.

mergetrain — локальная очередь слияния для параллельной работы LLM-агентов. Такие агенты используют большие языковые модели и работают в Git worktrees. mergetrain запускается на вашем компьютере. Поток (train) — это группа веток задач, поставленных в очередь. Проверка (gate) — настроенный тест или контрольное действие. Каждый агент коммитит изменения и ставит свою ветку в очередь. Один runner сливает ветки в порядке постановки в очередь и запускает проверки на объединённом результате. Обновление Git refs выполняется атомарно и только после явного подтверждения.

mergetrain предназначен для одного оператора, который управляет локальными репозиториями.

Для работы с mergetrain не нужны учётная запись, размещённая в облаке управляющая система, OAuth-приложение или телеметрия продукта. Состояние очереди и runner хранится на вашем компьютере. Внешние сервисы могут быть доступны только через настроенный вами Git remote и доверенные команды проверки или верификации.

Продолжайте работу, пока исправляются ошибки

Режим пакетной обработки включён по умолчанию: успешно прошедшие проверку изменения интегрируются первыми. Работа, требующая исправлений, возвращается агенту. Успешные изменения могут быть интегрированы, пока агент продолжает исправления.

Продолжайте работу во время проверок. Агенты приступают к следующим задачам, пока mergetrain проверяет предыдущие изменения. В этом 14-секундном цикле одновременно видны те же четыре агента.

Агенты могут продолжать работу в обоих режимах. В упорядоченном режиме незавершённая более ранняя отправка блокирует интеграцию последующих.

Сравнить два режима.

Приостановить демонстрацию или воспроизвести её снова ·

Воспроизвести непрерывный рабочий процесс

Как создана эта демонстрация

Эта иллюстрация основана на записанных результатах CLI.

Четыре дорожки обозначают роли агентов; буквы идентифицируют задачи, а не ID заданий в очереди.

Скрипты записи фиксируют изменения, созданные агентами, и подтверждения оператора в одноразовом локальном репозитории и bare remote. Скрипты не запускают сервис искусственного интеллекта.

Две задержки на тестовых проверках позволяют воспроизводить параллельную работу: задачи E и F коммитятся во время проверки A и B, затем работа над черновиками G и H начинается во время проверки E и F.

Во всех трёх случаях публикация сохраняет подтверждение и стандартную повторную проверку. Свежий клон итогового remote успешно проходит шесть тестов.

Затем G и H обновляются на основе этого результата без потери изменений. Там же начинаются задачи I и J. Эти четыре черновика остаются неотправленными. Агенты или оператор создают, исправляют, обновляют и повторно отправляют работу; mergetrain проверяет и интегрирует её. 14-секундная анимация повторяет этот записанный отрезок с сокращёнными интервалами.

Проблема

Worktrees позволяют нескольким агентам редактировать один репозиторий, не используя общую рабочую копию.

Но они не определяют порядок интеграции, не проверяют объединённый результат, не предотвращают гонки при отправке и не сообщают, что произошло, если ноутбук выключится во время отправки.

Без общего процесса интеграции оператор выбирает порядок веток и устраняет проблемы, возникающие при их объединении. Оператор также повторно запускает тесты и контролирует отправку изменений. Постоянное повторение этих действий может замедлить параллельную работу.

mergetrain сохраняет этот процесс в надёжной локальной очереди:

ветки агентов → локальная очередь → изолированная интеграционная рабочая копия → общие проверки
               → явное подтверждение → одна атомарная отправка → проверка после отправки

Кому подойдёт mergetrain?

Используйте mergetrain, если:

• несколько кодирующих агентов в течение дня завершают работу над ветками одного репозитория;

• агенты работают в Git worktrees и должны ставить ветки в очередь, а не отправлять их напрямую в ветки для публикации;

• перед интеграцией необходимо проверить объединённый результат локальными тестами;

• вы хотите обрабатывать без участия оператора только задания, на которые было выдано явное предварительное подтверждение; или

• вам нужна единая локальная панель для очередей и runner в нескольких репозиториях.

Инструмент не зависит от конкретной системы-обвязки: Codex, Claude Code, agy, скрипты и люди используют один и тот же CLI и JSON-контракт.

Запускаете несколько сессий Claude Code или Codex на одном ноутбуке? В руководстве для одного ноутбука описаны worktrees, интеграция без участия оператора, ресурсоёмкие проверки, режимы сна и тихие периоды, защита от отправки и отчёты о результатах. Все рекомендации проверены на одноразовых репозиториях.

Кому mergetrain не подойдёт?

Скорее всего, mergetrain вам не нужен, если:

• один человек или агент интегрирует по одной ветке за раз;

• каждое изменение уже проходит через PR и встроенную в вашу систему управления репозиториями очередь слияния;

• вам нужен размещённый в облаке интерфейс проверки, система разрешений для всей организации или удалённый сервис runner; или

• вы ищете универсальную очередь заданий, CI-провайдера или платформу развёртывания.

Командам, которые работают через PR, подойдут GitHub Merge Queue или GitLab Merge Trains. mergetrain предназначен для локальной интеграции изменений от агентов, работающих преимущественно в worktrees, — с PR или до его создания.

По умолчанию — пакетная обработка, при необходимости — упорядоченная

Начните с batch — это режим по умолчанию. Он подходит для независимой работы параллельных агентов. Runner объединяет доступные к моменту запуска задания и не ждёт завершения работы всех агентов. Совместимые изменения могут быть интегрированы, пока агент исправляет неудачно прошедшую проверку отправку.

Используйте ordered, если каждое изменение нужно интегрировать отдельно и необходимо сохранить исходный порядок отправки при сбоях и повторных попытках.

Сравнение	batch (по умолчанию)	ordered (необязательный режим)
Пример работы агентов	A исправляет вход в систему, B добавляет фильтры поиска, C обновляет экран администратора	A, B и C оптимизируют компилятор; каждое изменение измеряется относительно предыдущего интегрированного результата
Единица интеграции	Все доступные отправки вместе	По одной отправке за раз
Если B не проходит проверку	После изоляции B и успешной проверки A+C можно интегрировать	Можно интегрировать A; C ждёт, пока B не будет исправлена и интегрирована либо явно отменена
Положение B после retry	B перемещается в конец очереди	B сохраняет исходную позицию и остаётся перед C

В обоих режимах агенты могут приступить к следующей задаче после передачи изменений. В обоих режимах сохраняются подтверждение публикации и стандартная повторная проверка перед отправкой. При упорядоченной обработке проверки могут запускаться чаще, поскольку каждая отправка интегрируется отдельно. Очерёдность определяется моментом отправки, а не началом работы агента, и не отражает зависимости между изменениями.

Упорядочивание заканчивается после успешной интеграции в Git. Предупреждения о проверке после отправки остаются видимыми, пока продолжается обработка последующих изменений; если результат отправки неясен, требуется сверка состояния.

Доступность: режим ordered поддерживается в версии 3.6.0 и новее.

Для обычной параллельной работы агентов используйте batch — режим по умолчанию.

См. примеры работы агентов,

настройку и инструкции по обновлению.

Границы контроля

Lease-токены блокируют одновременную работу и устаревшие runner mergetrain. Они не перехватывают произвольную команду git push, которую может выполнить агент задачи, если у него есть доступ к shell и учётные данные для интеграционной ветки. Чтобы правило «отправку выполняет только один runner» гарантировалось технически, а не зависело от соблюдения договорённостей, используйте следующую схему:

агенты задач: коммитят изменения и ставят в очередь точный SHA; без учётных данных для отправки в интеграционную ветку
runner:       отдельная учётная запись для публикации
remote:       защищённая интеграционная ветка; отправка только runner или через проверенный PR

Если учётные данные не разделены, а remote не защищён, mergetrain всё равно обеспечивает безопасную сборку потока и восстановление после сбоев, но не может помешать участнику обойти очередь. См. границы безопасности.

Запустите настоящую демонстрацию

uvx mergetrain demo

Демонстрация создаёт одноразовый репозиторий и локальный bare remote, а затем проводит четыре настоящие ветки через слияние в порядке постановки в очередь, сбой проверки, обнаруживаемый только на объединённом результате, определение ветки, вызвавшей конфликт, и публикацию совместимого потока. Используйте --keep, чтобы позднее изучить результат. Добавьте --brief --pause, чтобы прочитать описание каждого шага перед продолжением. В расширенной записи рабочего процесса также показаны исправления, коммиты во время проверки, следующая пакетная обработка и три проверенных локальных развёртывания.

Полная запись работы CLI

Установка и первый запуск

# Установка CLI на уровне системы
uv tool install mergetrain          # or: pipx install mergetrain
# macOS: brew install yongjip/tap/mergetrain

# Codex: добавьте Git marketplace, затем установите нативный skill и закреплённый MCP-сервер
codex plugin marketplace add yongjip/mergetrain --ref main
codex plugin add mergetrain@mergetrain

# agy: установите нативный skill и закреплённый MCP-сервер
agy plugin install https://github.com/yongjip/mergetrain

Инструкции по настройке VS Code / GitHub Copilot или прямому подключению MCP см. в

руководстве по установке MCP и подтверждению развёртывания.

Инициализируйте репозиторий:

cd /path/to/your/repo
mergetrain init --project my-app --write

Добавьте в .mergetrain.yaml как минимум одну проверку проекта. В новой конфигурации

указано gates: [], поэтому проверки проекта не запускаются. Для Python-проекта,

в котором используется pytest:

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

Используйте команды тестирования, подходящие для вашего проекта. Проверки не должны

изменять собранную рабочую копию. Команда init также создаёт файлы

AGENTS.mergetrain.md и CLAUDE.mergetrain.md. Добавьте ссылки на них в имеющиеся

у вас AGENTS.md или CLAUDE.md.

Перед созданием рабочих деревьев для задач зафиксируйте конфигурацию и инструкции

и интегрируйте их обычным для вас способом.

После того как агент задачи закоммитит чистую ветку в собственном рабочем дереве:

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

После добавления задачи в очередь агент завершает работу. Из рабочей копии оператора

выполните следующие команды, когда проверка и развёртывание будут разрешены:

mergetrain status
mergetrain deploy

Если проверки выполняются долго, запустите mergetrain validate заранее: эта команда

не отправляет изменения и подготавливает один конкретный поезд в состоянии Ready для

последующего подтверждения командой deploy.

deploy выполняет настроенное атомарное обновление ссылок Git; это не означает

выпуск приложения через App Store, Kubernetes или другого провайдера.

Агенты создают коммиты и добавляют задачи в очередь. Один исполнитель отвечает за

весь процесс: слияние → тестирование → отправка → проверка.

Автономные демоны обрабатывают только задания, которые человек явно добавил в очередь

с помощью --auto. Для заданий, добавленных вручную, команда daemon --validate-only

может выполнять слияние и проверки в фоновом режиме, но останавливается на этапе

подтверждения проверенного поезда и никогда не отправляет изменения.

См. краткое руководство

по настройке, работе демона и конфигурации Hub для нескольких репозиториев.

Интеграция параллельных сеансов Claude Code и рабочих деревьев Codex

Используйте очередь слияния Git-рабочих деревьев, если параллельные сеансы Claude Code

или параллельные рабочие деревья Codex создают закоммиченные ветки в одном репозитории.

Руководство по установке плагина

поможет подключить любой из этих клиентов к очереди. Агенты задач создают коммиты,

добавляют ветки в очередь и завершают работу. Отдельно уполномоченный исполнитель

тестирует совокупность веток и отвечает за отправку изменений.

Для рабочих деревьев под управлением Orca см. руководство по настройке Orca и очереди:

в нём приведены проверенные команды терминала, описаны совместная работа с очередью,

проверка и восстановление.

В руководстве для агентов Orca описаны настройка нативных плагинов Codex, Claude Code и

agy, а также ограниченные по объёму запросы для задач и проверки.

Почему недостаточно рабочих деревьев и git merge?

Рабочие деревья решают задачу параллельного редактирования. mergetrain отвечает

за последовательную интеграцию.

Задача интеграции	Рабочие деревья + ручное слияние	mergetrain
Порядок интеграции	Человек или агент каждый раз выбирает порядок	Постоянная очередь в порядке добавления
Проверка объединённых изменений	Проверки запускаются вручную после каждого слияния	Проверки выполняются для точно собранного поезда
Сбой при объединении веток	Причину приходится искать вручную	Изолированные запуски выявляют конфликтующую пару
Ответственность за отправку	Каждый сеанс может одновременно изменять ссылку	Отправкой управляет один исполнитель, защищённый арендой
Подтверждение	Договорённость о работе в оболочке	Явное намерение выполнить validate или deploy; --auto включается отдельно
Восстановление после сбоя	Причину приходится восстанавливать по локальным журналам	Состояние SQLite сверяется с удалёнными ссылками

Агенты по-прежнему работают в отдельных рабочих деревьях. Один исполнитель mergetrain

интегрирует их закоммиченные изменения.

Почему не использовать очереди слияния GitHub или GitLab?

Они решают похожую задачу, но рассчитаны на другую модель работы.

	Очередь платформы Git	mergetrain
Основная единица работы	Pull/merge request	Закоммиченная локальная ветка задачи
Проверка	Группа слияния платформы + удалённая CI	Локально собранный поезд + проверки оболочки
Ревью	Встроенное обсуждение и подтверждения	Интерфейса для ревью кода нет
Инфраструктура	Интеграция с платформой и размещённые сервисы	Локальные SQLite и рабочие деревья Git, любой удалённый Git-репозиторий
Оптимальный вариант	Команды, работающие через PR, и распределённое ревью	Высокопроизводительная локальная интеграция изменений агентов

Эти модели можно использовать вместе: отправить проверенный поезд в ветку для ревью

и создать один PR либо оставлять отдельные PR для изменений, требующих обсуждения.

В руководстве по работе с PR

описаны сценарии с прямой интеграцией, одним PR, разделением на несколько PR и только

проверкой.

Восстановление после прерванной отправки Git

Остановка или тайм-аут при отправке Git не позволяют понять, принял ли удалённый

репозиторий обновление. mergetrain сохраняет данные о развёртывании. Процедура

восстановления сначала проверяет удалённые ссылки, и только потом повторяет попытку.

Начните с команды mergetrain status --json и выполните указанное действие по

восстановлению, учитывая требования к подтверждению. См.

руководство по восстановлению.

Основные гарантии безопасности

• Точная идентичность поезда. Подтверждение привязано к HEAD коммитам задач и базе

  интеграции. Изменение веток или перемещение базы не позволяет незаметно повторно

  использовать это подтверждение.

• Проверка объединённых изменений перед отправкой. Успешной проверки отдельной

  ветки недостаточно. Собранный поезд должен пройти настроенные проверки, иначе

  изменения не будут интегрированы.

• Один исполнитель mergetrain с защитой от устаревших операций. Записи SQLite

  о захвате задачи и токены аренды не дают параллельным или устаревшим исполнителям

  mergetrain изменять один и тот же поезд. Для дополнительной защиты на удалённой стороне

  также требуется описанная выше схема учётных данных.

• Атомарное обновление удалённых ссылок. Ссылки на содержимое и постоянная ссылка

  восстановления refs/mergetrain/deploys/ обновляются вместе.

• Восстановление по состоянию удалённого репозитория. Маркеры опережающей записи

  и закреплённые коммиты позволяют команде reconcile определить, был ли принят

  прерванный push, не повторяя успешное развёртывание и не считая отсутствующим

  выполненное.

• Явное разрешение на автоматизацию. Обычный запуск никогда не выполняет

  развёртывание. Демоны обрабатывают только заранее одобренные задания --auto,

  если их назначение и политики проверок, повторного использования и верификации

  по-прежнему совпадают. Для выполнения deploy через MCP всё равно требуется

  подтверждение человека, которое можно однозначно связать с ним.

• Единая точка просмотра состояния. Команда status преобразует внутренние данные

  в состояния Waiting, Running, Ready, Attention и Done, а также сообщает следующую

  безопасную команду. Команда inspect предоставляет подробные данные на уровне

  задания только при необходимости.

Состояние очереди, блокировки, сборка поезда и проверки выполняются локально.

Настроенный удалённый Git-репозиторий и проверка после отправки всё ещё могут

использовать внешние сервисы. Команды проверок и верификации — это доверенный код;

перед включением автономной обработки заданий ознакомьтесь с

границами безопасности.

Эти гарантии проверяются на macOS и Linux с Python 3.10–3.14, а также в Windows,

включая внедрение сбоев при вызове git push --atomic с реальным Git. В отдельном

репозитории для длительных испытаний были успешно интегрированы 20 поездов: показатель

успешной интеграции составил 100%. Испытания включали запланированное восстановление

после конфликтов и сверку состояния после принудительно остановленного push; результат

сверки совпал с состоянием удалённого репозитория. См.

результаты длительных испытаний,

а затем выполните mergetrain stats --json, чтобы просмотреть данные из собственной

очереди.

Подробнее

• Начало работы: Краткое руководство ·

Установка ·

CLI ·

Конфигурация

• Разобраться: Дизайн и архитектура ·

Контракт для машин ·

Сравнение рабочих процессов с PR

• Эксплуатация: Эффективная работа ·

Сбои и восстановление ·

Обновление ·

Демон ·

Центр управления несколькими репозиториями

• Доверие и расширение: Безопасность ·

Контракт для агентов ·

Тест производительности по внедрению агентов ·

Тест поиска без упоминания названия продукта ·

Тест локальной работы нескольких агентов ·

MCP-сервер ·

Шаблон адаптера ·

Границы продукта

Стабильный интерфейс

Стандартный CLI намеренно ограничен шестью командами:

init  status  enqueue  validate  deploy  inspect

Версия 3 — это долгосрочная грамматика продукта. Выпуск версии 4 не планируется: новые

возможности должны вписываться в эти команды или оставаться в расширенных интерфейсах для операторов, а

контракты v3 для JSON и MCP будут развиваться с сохранением обратной совместимости, за исключением изменений версий контрактов,

зафиксированных в

политике совместимости.

Последний опубликованный выпуск указан на значке PyPI выше.

Сообщения об ошибках и отчёты об эксплуатации можно отправлять через

GitHub.

Лицензия

Распространяется по лицензии MIT.