mergetrain

병렬 LLM 에이전트를 위한 로컬 병합 대기열

mergetrain은 LLM(대규모 언어 모델)을 사용하는 코딩 에이전트의 커밋된 브랜치를 통합합니다. 에이전트는 각자의 Git worktree에서 작업합니다. 대기열과 실행기는 사용자의 머신에서 동작합니다.

각 에이전트가 커밋하고 브랜치를 대기열에 넣습니다. 실행기 하나가 대기열 순서대로 브랜치를 합칩니다. 별도 worktree에서 합쳐진 결과를 검사한 뒤, 명시적 승인을 받아 설정한 Git ref를 한 번의 원자적 push로 갱신합니다.

병렬 Claude Code 세션과 Codex worktree의 통합 검사

병렬 Claude Code 세션, Codex worktree 또는 다른 코딩 에이전트가 만든 브랜치를 push 전에 함께 검사해야 할 때 사용합니다.

각 브랜치가 개별 테스트를 통과해도 합친 뒤에는 실패할 수 있습니다. 로컬 Git 병합 대기열은 합쳐진 결과에 설정한 검사를 실행합니다. 에이전트 하나가 브랜치 하나에서 작업한다면 일반 Git만으로도 충분할 수 있습니다.

기본은 batch입니다

위 GIF는 기본 batch 모드의 예시입니다. 통과한 작업은 먼저 반영합니다. 수정이 필요한 작업은 에이전트에게 돌아갑니다. 그 수정이 진행되는 동안 통과한 작업을 먼저 반영할 수 있습니다.

일반적인 병렬 개발에는 batch를 사용하세요. 대기 중인 제출을 모아 검사합니다. 모든 에이전트가 끝날 때까지 기다리지 않습니다.

예를 들어 A는 로그인 오류를 고치고, B는 검색 필터를 추가하고, C는 관리자 화면을 수정합니다. B가 단독 검사에서도 실패하면 B를 분리하고 A+C를 검사할 수 있습니다. A+C는 검사를 통과하면 반영할 수 있습니다. B의 에이전트가 수정한 뒤 재시도하면 대기열 뒤에 들어갑니다.

ordered가 필요한 경우

변경 하나씩 반영하고 결과를 확인해야 할 때 ordered를 사용하세요. 예를 들어 컴파일러 에이전트가 상수 계산(A), 반복문(B), 레지스터 할당(C)을 최적화합니다. 각 변경의 성능을 직전에 반영된 결과와 비교합니다.

A가 먼저 반영됩니다. B가 실패하면 C의 반영은 기다립니다. B의 수정본은 실행기가 재시작되어도 C 앞의 원래 자리를 유지합니다.

두 모드 모두 에이전트는 다음 작업을 계속할 수 있습니다. ordered는 후속 작업의 반영을 기다리게 하고, 제출마다 따로 검사합니다. 승인과 기본 배포 전 재검사는 두 모드 모두 유지합니다.

ordered는 3.6.0부터 사용할 수 있습니다. 일반적인 병렬 작업에는 batch를 유지하세요. 각 제출이 순서대로 반영되어야 할 때 ordered를 선택하세요. 작업 예시와 업그레이드 절차를 확인하세요.

로컬 작업 흐름을 위한 도구

• 커밋된 브랜치를 위한 Git worktree 병합 대기열
• 합쳐진 결과에 실행할 검사 설정
• 원자적 Git push에 대한 명시적 승인
• 다양한 코딩 에이전트와 일반 Git 작업에서 사용

호스팅형 CI 서비스가 아닌, 사용자가 직접 운영하는 도구입니다. Git 권한과 검증 항목은 별도로 설정해야 합니다.

중단된 Git push 복구

push가 중단되어 응답을 받지 못했다고 해서 실패한 것은 아닙니다. mergetrain은 push 근거를 기록합니다. 복구 절차는 원격 Git ref를 확인한 뒤 다음 행동을 선택합니다. 자세한 내용은 실패와 복구 안내를 확인하세요.

시작하기

통과한 작업은 먼저 반영합니다. 검사 중에도 다음 작업을 진행합니다. 14초 애니메이션은 같은 에이전트 네 개로 이 두 장면을 보여줍니다. 새 작업에는 에이전트 칸 안에 Next task를 표시합니다. 반영된 변경은 프로젝트에 남습니다. 영상이 재생되지 않으면 GIF 링크를 사용하세요.

uvx mergetrain demo로 기본 CLI 데모를 실행할 수 있습니다. 확장된 연속 작업 기록은 수정, 두 번의 동시 진행, 세 번의 승인·기본 재검사·배포를 포함합니다. 최종 로컬 원격 저장소의 새 복제본에서 테스트 6개가 통과했습니다.

캡처 스크립트는 임시 저장소에서 에이전트가 작성한 코드와 운영자의 승인을 재현합니다. AI 서비스를 직접 실행하지 않습니다. 검사 대기 지점 두 개로 동시 진행을 재현합니다. A·B 검사 중 E·F를 커밋하고, E·F 검사 중 G·H 초안을 시작합니다. 이후 G·H는 수정을 유지한 채 최신 결과를 가져옵니다. I·J도 그 결과에서 시작합니다. 네 초안은 아직 제출하지 않은 작업입니다. 화면의 네 칸은 에이전트 역할을, 문자는 작업을 나타냅니다. 14초 애니메이션은 이 실행 구간을 반복합니다. 실제 명령과 실행 결과도 확인할 수 있습니다.

설치 방법은 GitHub README에 있습니다. PyPI에서도 패키지를 확인할 수 있습니다.

MIT 라이선스로 공개되어 있습니다.