<h1 >Foremerge</h1>
<p align="center">
<img src="https://raw.githubusercontent.com/naw103/foremerge/HEAD/docs/assets/foremerge-readme-banner.png" alt="Foremerge: Catch intent conflicts before code conflicts" width="100%">
</p>
CI
crates.io
License: Apache-2.0
Foremerge는 Git 위에 구축된 코딩 에이전트용 오픈 소스 조정 프로토콜입니다. 에이전트들은 격리된 작업 트리(worktrees)를 유지하면서 의도(intent), 의미론적 주장(semantic claims), 종속성(dependencies), 임시 변경 세트(provisional ChangeSets), 결정(decisions), 검증(validation), 그리고 출처(provenance)를 공유합니다.
| 에이전트에게 설치하도록 지시하기 | → | 완료 | → | 충돌 발생 전에 확인하기 |
|---|
| Claude Code, Codex 또는 Cursor에 한 줄 붙여넣기 | | Foremerge를 설치하고 연결합니다 | | 모든 에이전트가 별도의 작업 트리에서도 다른 에이전트가 무엇을 변경하려 하는지 볼 수 있습니다 |
상태: Foremerge 0.5.1은 1.0 미만의, 로컬 우선(local-first) MVP입니다. CLI, JSON API, MCP 서버, SQLite 스토어, 결정론적 충돌 감지기(deterministic conflict detector), 그리고 검증 게이트가 적용된 라이프사이클이 구현되었습니다. 공개 스키마는 여전히 변경될 수 있습니다. 게시된 벤치마크 결과는 아직 존재하지 않으며, 기계 간의 조정은 이 프로젝트의 범위를 벗어납니다.
작동 방식
만약 두 개의 AI 에이전트가 동시에 같은 프로젝트에서 작업하고 있다고 가정해 봅시다. 각각은 자체 코드 사본을 가지므로 파일에 대해 충돌하지 않습니다. 둘 다 완료됩니다. 둘 다 올바르게 보입니다. 그러다가 그들이 서로의 작업을 취소했다는 것을 발견합니다.
Git은 텍스트를 비교할 뿐 의도를 비교하지 못하기 때문에 그러한 충돌에 대해 경고해 줄 수 없습니다. Git이 막는 경우는 두 에이전트가 동일 파일의 같은 부분을 수정할 때입니다. 하지만 각자 자체적으로 완벽하게 합리적인 두 개의 수정 사항이 서로 다른 파일에 적용되는 경우를 포착하지 못합니다. 만약 한 에이전트가 모든 호출자를 새로운 StripePaymentService로 이동시키고, 다른 에이전트가 기존의 PaymentService에 PayPal 지원을 추가한다면, 겹치는 부분이 없으므로 Git은 아무 문제 없이 두 가지 변경 사항을 병합하지만, 이 경우 PayPal 관련 작업은 더 이상 어떤 클래스도 호출하지 않는 곳에 방치되는 상황이 발생합니다.
Foremerge는 에이전트가 작업을 수행하기 전에 자신이 무엇을 할 것인지 공지하도록 함으로써 이 문제를 해결합니다.
- 각 에이전트는 자신이 건드릴 대상을 말합니다. 코드 자체가 아니라, "저는
sendEmail 함수를 변경할 것입니다"와 같은 대상만 말하는 것입니다.
- 모든 에이전트가 하나의 공유된 목록에서 읽습니다. 이는 프로젝트의
.git 폴더 안에 있는 작은 데이터베이스로, 사용자의 기기에 있는 모든 에이전트(Claude, Codex, Cursor 등)는 동일한 그림을 보게 됩니다.
- 두 계획이 충돌하면 즉시 알림을 받습니다. Foremerge는 두 에이전트의 이름을 언급하고, 그들의 계획이 왜 충돌하는지 설명하며, 작업을 어떻게 분할해야 하는지 제안합니다. 이 시점에서는 두 작업 트리 모두 깨끗하므로 버려야 할 작업이 없습니다.
이는 공유 화이트보드라고 생각하시면 됩니다. 에이전트가 시작하기 전에 자신이 무엇을 작업할 것인지 적고, 다른 모든 사람이 이미 적은 내용을 읽는 방식입니다.
Foremerge가 의도적으로 하지 않는 두 가지 사항이 있습니다. 파일에 잠금(lock)을 걸거나 에이전트를 차단하지 않습니다. 왜냐하면 단 하나의 충돌한 에이전트만 전체 시스템을 멈추게 할 수 있기 때문에, 경고는 자문적이며 사용자가 통제권을 유지합니다. 또한 모델에게 충돌 판단을 요청하지 않으므로 동일한 입력은 항상 동일한 답변을 생성합니다.
Git이 아직 포착할 수 없는 충돌
Agent A: PaymentService를 StripePaymentService로 교체
Agent B: PaymentService에 PayPal 지원 추가
이 에이전트들은 같은 라인을 건드리지 않으면서 서로 다른 트리에서 작업할 수 있습니다. 하지만 계획 자체는 여전히 충돌합니다. 하나는 확장 지점(extension point)을 제거하는 반면, 다른 하나는 그 확장 지점에 의존하기 때문입니다.
두 에이전트 모두 동일한 symbol:PaymentService 스코프를 선언하는데, 한쪽은 이를 replace(대체)할 것이라고 하고 다른 쪽은 extend(확장)할 것이라고 합니다. Foremerge는 두 에이전트가 코드를 작성하기 전에 이 두 가지 선언을 비교하고, PaymentProvider와 같은 안정적인 추상화(abstraction)를 조정하도록 제안하며 HIGH 경고를 발생시킵니다. 이러한 제안은 자동 아키텍처 결정이나 강제 잠금(hard lock)이 아닌 설명 가능한 증거입니다.
작업 내용이 요약본에서 읽어낸 것이 아니라 선언된 것이기 때문에, 각 에이전트가 계획을 어떻게 표현했는지는 중요하지 않습니다. "Consolidate payments onto Stripe"와 "Replace PaymentService with Stripe"는 동일한 결론에 도달합니다.
Git은 여전히 영구적인 저장소(durable repository)입니다. Foremerge는 그 위에 누락된 공유 인지(shared awareness)를 공급합니다.
Terminal rendering of an actual Foremerge release demo detecting the PaymentService conflict before either worktree changed
examples/terminal-session.txt에서 캡처한 실제 충돌 필드를 렌더링한 것입니다. 표시된 명령어는 보여진 jq 필터를 사용하며, 출력은 가독성을 위해 요약되었습니다.
빠른 시작: 5분 안에 첫 충돌 해결하기
코딩 에이전트에게 맡기기
조정하고자 하는 저장소 내부에서 Claude Code, Codex 또는 Cursor에 다음 내용을 붙여넣으세요.
Set up Foremerge in this repository so we can coordinate parallel agents.
1. Install it: curl -fsSL https://foremerge.com/install.sh | sh
...
4단계는 이 저장소의 실제 테스트 명령어로 조정하세요. 3단계는 클라이언트에게 MCP 서버를 활성화하도록 요청하므로, 실행 전에 프롬프트를 표시할 것입니다. Codex 등록은 사용자 레벨이지만, 하나의 등록으로 모든 저장소에 서비스를 제공합니다: 코디네이션을 원하는 저장소 내부에서 Codex를 시작하세요.
직접 수행하기
최신 Git과 jq가 필요합니다. 사전 빌드되었고 체크섬이 검증된 릴리스 바이너리(macOS 및 Linux용; 스크립트는 ~/.local/bin에 설치됩니다)를 설치하세요.
curl -fsSL https://foremerge.com/install.sh | sh
[!TIP]
두 개의 명령어, 하나의 프로그램. 이 명령은 foremerge와 더 짧은 이름으로 동일한 바이너리인 fmg를 설치합니다. 따라서 fmg status와 foremerge status는 같은 작업을 수행합니다. 아래 예시에서는 foremerge로 명시했습니다. 선호하는 어느 것을 사용해도 됩니다.
또는 macOS나 glibc가 있는 Linux에서 npm을 통해 설치할 수 있습니다. 패키지는 동일한 릴리스 바이너리를 포함하므로, 설치 시 아무것도 컴파일하거나 다운로드되지 않습니다:
Windows용 npm 패키지는 아직 게시되지 않았습니다. Windows에서는 릴리스 페이지를 사용하십시오.
또는 Rust 1.85 이상으로 소스에서 빌드할 수 있습니다: cargo install --locked --git https://github.com/naw103/foremerge foremerge, 또는 체크아웃된 디렉토리에서 cargo install --locked --path .을 사용하십시오. Windows 바이너리는 릴리스 페이지에 있습니다. 업데이트하려면, 설치한 방식과 동일하게 업그레이드한 다음 foremerge setup을 다시 실행하고 에이전트 클라이언트를 재시작하십시오. Foremerge 업그레이드하기에서는 각 단계가 왜 중요한지 설명합니다. 그런 다음, 조정하려는 저장소 내부에서:
foremerge init
foremerge doctor
설치 프로그램, 릴리스 아카이브 및 cargo install 모두 0.4.0 버전부터 두 이름(foremerge, fmg)을 포함합니다. 만약 PATH의 다른 무언가가 이미 fmg에 응답하고 있다면, 설치 프로그램은 그것을 건드리지 않고 가리는 대신 그렇게 알려줍니다.
이 저장소에서 사용되는 모든 클라이언트에 대해 네이티브 스킬과 MCP 엔트리를 설치한 다음, 에이전트가 요청할 수 있는 신뢰할 수 있는 검사(checks)를 이름으로 정의하십시오:
foremerge setup all
foremerge checks set test -- cargo test --all-targets
foremerge doctor --client all
Acceptance는 검증(verification)-게이트가 결정합니다: Foremerge는 에이전트의 말만 듣기보다는 자체적으로 검사를 실행합니다. 전체 CI 스위트보다는 빌드나 타입 체크와 같이 실제로 손상된 핸드오프를 잡아낼 수 있는 빠르고 실질적인 검사 하나를 선택하세요. 이 게이트가 다른 에이전트들이 작업을 완료된 것으로 간주할지 결정하며, CI를 대체하지는 않습니다. 만약 이 리포지토리에 의미 있게 검증할 것이 없다면, 항상 통과하는 검사를 등록하기보다는 한 번에 명시하세요:
foremerge checks policy advisory
이렇게 수락된 작업은 사유와 함께 UNVERIFIED로 기록되므로, 감사 추적(audit trail)이 실제로 실행되지 않은 검사가 실행되었다고 암시하는 일이 없습니다. foremerge doctor는 등록된 검사들이 여기서 실제로 실행될 수 있는지 보고하며, 이는 에이전트 워크트리에서 중요합니다. 왜냐하면 종속성 디렉터리는 보통 .gitignore 처리되며 git worktree add가 이를 생성하지 않기 때문입니다.
하나의 클라이언트를 위해 setup codex, setup claude, 또는 setup cursor를 사용하세요. Setup은 관련 없는 설정(프로젝트 MCP JSON 내 키 순서 포함)을 보존합니다. Foremerge를 업그레이드하면 자체 편집되지 않은 스킬 파일이 제자리에 새로 고쳐지지만, 사용자가 편집한 스킬 파일이나 다른 Foremerge MCP 항목은 명시적으로 --force 플래그를 전달하지 않는 한 절대 대체되지 않습니다. setup all은 모든 클라이언트를 시도하고 각 결과를 보고하며, 하나라도 실패하면 0이 아닌 값을 반환합니다. Codex MCP 등록은 사용자 레벨이며 모든 리포지토리에 서비스를 제공하고, Codex가 시작된 디렉터리에서 해결됩니다. 에이전트 클라이언트 설정을 참조하세요.
init은 리포지토리의 Git 공통 디렉터리 아래에 로컬 조정 상태를 생성합니다. 이는 추적되는 파일을 변경하지 않습니다. 다음 no-worktree 세션만으로도 사전 코드 감지를 연습하기에 충분하며, 실제 코딩 에이전트는 자신의 격리된 워크트리를 그리고 실제 모델 식별자를 등록해야 합니다.
STRIPE_AGENT=$(
foremerge --json agent register \
--name stripe-agent \
...
첫 번째 명령어는 로컬 실행에서 발생하는 실시간 발견 사항을 출력합니다. 두 번째 명령어는 related_work를 출력하는데, 이는 다른 에이전트의 의도와 선언된 모든 연산과 겹치는 모든 범위를 포함합니다. Foremerge는 어떤 부분이 중복되는지 알려주고, 사용자는 그것이 무엇을 의미하는지 결정하여 foremerge assess record로 기록합니다. 먼저 파일이 변경될 필요는 없습니다. examples/terminal-session.txt에서 캡처된, 명확하게 레이블링된 트랜스크립트를 검토하세요.
클레임(Claim)은 두 에이전트 중 어느 쪽도 차단하지 않으면서 소유권 컨텍스트를 추가합니다:
foremerge --json work claim \
--agent "$STRIPE_AGENT" \
--intent "$STRIPE_INTENT" \
...
두 클레임 모두 성공합니다. 두 번째 응답에는 클레임이 배정된 자문(leased advisory)일 뿐, 결코 독점적인 소유권이 아니기 때문에 중복 경고가 포함됩니다.
Real terminal recording: two agents declare intents on symbol:PaymentService and Foremerge raises the HIGH destructive_vs_additive finding before either writes code
릴리스된 0.4.0 바이너리에 대해 기록되었습니다. 모든 명령어와 그 출력은 실제입니다.
Git과 통합되는 방식
코딩 에이전트 A 코딩 에이전트 B
|
격리된 작업 트리 A 격리된 작업 트리 B
...
모든 프론트엔드는 동일한 서비스와 스토어를 사용합니다. 의미론적 그래프(semantic graph)는 다음과 같습니다:
Agent → Task → Intent → Claim → Symbol → Dependency
→ ChangeSet → Test → Result → Decision → Provenance
뮤테이션(Mutations)은 타입이 지정된 SQLite 프로젝션(projections)을 업데이트하고, 그래프 엣지(edges)를 물질화하며, 하나의 트랜잭션 내에서 해시 체인으로 연결된 의미론적 이벤트(semantic event)를 추가합니다. 이 로그는 조작 방지 증거(tamper evidence)로 유용하며, 원격 신원 서명이나 분산 합의(distributed consensus)가 아닙니다.
Git 작업 트리: 격리된 파일, 공유된 인식
Foremerge는 Git 공통 디렉터리를 해결하고 기본 데이터베이스를 다음 위치에 저장합니다:
<git-common-dir>/foremerge/state.sqlite3
연결된 작업 트리들은 체크아웃된 파일은 분리되어 있지만, 그 공통 디렉터리를 공유합니다. 기본 Git을 감싼 Foremerge의 얇은 래퍼(wrapper)로 작업 트리를 생성하세요:
foremerge worktree create \
--branch agent/paypal \
--path ../payments-paypal \
...
같은 리포지토리 내의 다른 워크트리도 등록된 에이전트와 그 의도를 즉시 볼 수 있습니다. --database PATH 또는 FOREMERGE_DB로 스토리지를 덮어쓸 수 있지만, 모든 로컬 에이전트는 상태를 공유하기 위해 동일한 데이터베이스를 가리켜야 합니다. MVP는 SQLite를 여러 머신에 복제하지 않으므로, 네트워크 마운트된 데이터베이스에서 분산 안전성을 추론하지 마십시오.
Foremerge는 ChangeSet 지문(fingerprints)과 승인된 참조(accepted refs)를 위해 Git 상태를 스냅샷합니다. 이는 자동으로 병합(merge), 리베이스(rebase), 체리픽(cherry-pick), 푸시(push) 또는 대상 브랜치를 업데이트하지 않습니다.
의미론적 워크플로우 (Semantic workflow)
INTENT ─claim→ CLAIMED ─start→ IN_PROGRESS ─publish→ PROVISIONAL
─validate current fingerprint→ VALIDATED
─accept gates→ ACCEPTED ─record Git ref→ COMMITTED
지원되는 범위 종류(scope kinds)는 다음과 같습니다:
symbol api schema config infra test migration env file component contract domain
가장 좁고 유용한 의미론적 범위를 게시하십시오. 파일 경로만으로는 API, 구성, 스키마, 인프라 및 크로스-언어 충돌을 놓칩니다.
일반 명령어:
