Mergetrain: 병렬 Claude Code 세션에서 푸시 충돌을 방지하는 로컬 병합 큐

여러 Claude Code 세션을 병렬로 실행 중이라면, 아마도 덮어쓰기 문제를 겪어보셨을 겁니다: 브랜치 A는 테스트를 통과하고, 브랜치 B도 통과하지만, A 다음 B를 적용하면 깨지는 경우입니다. 워크트리는 편집을 분리하지만, 배포까지 분리하지는 않습니다. 그리고 "main에 푸시 금지" 같은 CLAUDE.md 규칙은 한 세션이 최악의 순간에 이를 위반할 때까지 유지됩니다. 규칙은 강제가 아닙니다.

Mergetrain은 이 문제를 해결하는 로컬 병합 큐입니다. 전적으로 사용자 컴퓨터에서 실행되며, 서버, GitHub 앱, CI 서비스, 런타임 의존성이 필요 없습니다. MIT 라이선스입니다.

작동 방식

• 각 Claude Code 세션은 자체 워크트리에서 작업하며 푸시 대신 대기열에 추가합니다(mergetrain enqueue).
• 저장소 소유의 사전 푸시 훅이 main으로의 직접 푸시를 차단합니다.
• 단일 러너가 대기열에 있는 브랜치를 origin/main 위에 "기차"로 조립하고, 전체 기차에 대해 한 번 게이트(테스트 + 전체 Unity 빌드)를 실행한 후 원자적으로 푸시합니다.
• mergetrain hub는 머신의 모든 저장소에 대해 읽기 전용 대시보드를 제공합니다: 누가 게이트를 실행 중인지, 무엇이 배송 준비되었는지, 무엇이 주의를 필요로 하는지 확인할 수 있습니다. 에이전트는 동일한 정보를 JSON으로 읽습니다(hub status --json).
• 푸시 중간에 노트북이 꺼지면, mergetrain recover가 원격에 실제로 무엇이 배포되었는지 묻고 조정합니다. 아무것도 두 번 배송되지 않고, 잘못 레이블링되지 않습니다.
• 무인 배포가 절대 허용되지 않는 저장소는 --no-daemon으로 등록할 수 있습니다: 대시보드에는 보이지만, 자동 처리되지 않습니다.

시작하기

pip으로 설치: pip install mergetrain
그런 다음 mergetrain init을 실행하여 설정 파일과 에이전트가 자동으로 인식하는 CLAUDE.md 계약을 생성합니다.

자체 사용 결과

상업용 게임에서 3주 동안: 70개 이상의 기차가 배송되었고, 이후 덮어쓰기 문제는 단 한 번도 발생하지 않았습니다.

대상 사용자

병렬 AI 코딩 에이전트(Claude Code 등)를 실행하며, 호스팅된 PR 파이프라인이나 파일 잠금에 의존하지 않는 가벼운 로컬 통합 솔루션이 필요한 개발자.