Foremerge

Foremerge는 Git 위에 구축된 코딩 에이전트를 위한 오픈소스 조정 프로토콜입니다. 에이전트는 격리된 워크트리를 유지하면서 의도, 의미론적 클레임, 의존성, 임시 ChangeSets, 결정, 검증, 출처(provenance)를 공유합니다.

상태: Foremerge 0.4.0은 1.0 이전의 로컬 우선 MVP입니다. CLI, JSON API, MCP 서버, SQLite 저장소, 결정적 충돌 감지기, 검증 게이트 수명 주기가 구현되어 있습니다. 공개 스키마는 여전히 변경될 수 있습니다. 공유 멀티 머신 모드와 게시된 벤치마크 결과는 아직 존재하지 않습니다.

작동 방식

같은 프로젝트에서 두 AI 에이전트가 동시에 작업하고 있다고 가정해 보세요. 각자는 코드의 자신만의 복사본을 가지므로 파일을 두고 다투지 않습니다. 둘 다 작업을 끝냅니다. 둘 다 올바르게 보입니다. 그런데 알고 보니 서로의 작업을 취소해 버렸습니다.

Git은 그런 상황을 경고할 수 없습니다. Git은 텍스트만 비교하고 의도는 비교하지 않기 때문입니다. 두 에이전트가 같은 파일의 같은 부분을 수정하면 Git이 막아 줍니다. 그러나 각각 단독으로는 완전히 합리적이면서 서로 다른 파일에 들어가는 두 수정은 볼 수 없습니다. 한 에이전트가 모든 호출자를 새 StripePaymentService로 옮기는 동안 다른 에이전트가 기존 PaymentService에 PayPal 지원을 추가한다면 겹치는 것이 없으므로 Git은 불평 없이 둘 다 병합하고, PayPal 작업은 더 이상 아무도 호출하지 않는 클래스에 남겨집니다.

Foremerge는 에이전트가 작업을 하기 전에 무엇을 하려는지 선언하도록 함으로써 이 문제를 해결합니다.

1. 각 에이전트는 무엇을 건드릴지 말합니다. 코드가 아니라 대상만 말합니다. 예: "sendEmail 함수를 변경하겠습니다."

2. 모든 에이전트는 하나의 공유 목록을 읽습니다. 그것은 프로젝트의 .git 폴더 안에 있는 작은 데이터베이스이므로, 머신의 모든 에이전트(Claude든 Codex든 Cursor든)는 같은 그림을 봅니다.

3. 두 계획이 충돌하면 즉시 알 수 있습니다. Foremerge는 두 에이전트를 지목하고 계획이 왜 충돌하는지 설명하며 작업을 어떻게 나눌지 제안합니다. 그 시점에는 두 워크트리가 모두 깨끗하므로 버릴 작업이 없습니다.

공유 화이트보드라고 생각하면 됩니다. 에이전트는 시작하기 전에 작업할 내용을 적고, 다른 사람들이 이미 적어 둔 내용을 읽습니다.

Foremerge가 의도적으로 하지 않는 두 가지가 있습니다. 파일을 잠그거나 에이전트를 차단하지 않습니다. 에이전트 하나가 죽으면 전체 플릿(fleet)이 멈추게 되므로, 경고는 참고용이며 통제권은 사용자에게 있습니다. 또한 모델에게 충돌을 판단하도록 요청하지 않으므로, 같은 입력은 항상 같은 결과를 냅니다.

Related MCP server: batuta-mcp

Git이 아직 볼 수 없는 충돌

Agent A: Replace PaymentService with StripePaymentService
Agent B: Add PayPal support to PaymentService

이 에이전트들은 같은 줄을 건드리지 않고도 서로 다른 트리에서 작업할 수 있습니다. 그러나 계획은 여전히 충돌합니다. 하나는 확장 지점을 제거하는 반면 다른 하나는 그것에 의존합니다.

두 에이전트 모두 동일한 symbol:PaymentService 범위를 선언합니다. 하나는 replace하겠다고 하고 다른 하나는 extend하겠다고 합니다. Foremerge는 둘 중 하나가 코드를 작성하기 전에 이 두 선언을 비교하고 HIGH 권고를 발생시킨 다음, PaymentProvider와 같은 안정적인 추상화를 위해 조율할 것을 제안합니다. 그 제안은 설명 가능한 증거이지, 자동 아키텍처 결정이나 강제 잠금이 아닙니다.

작업은 요약에서 읽어내는 것이 아니라 선언되므로, 각 에이전트가 계획을 어떻게 표현했는지는 중요하지 않습니다. "결제를 Stripe로 통합"과 "PaymentService를 Stripe로 교체"는 같은 판정에 도달합니다.

Git은 영속적인 저장소로 남습니다. Foremerge는 그 위에 빠져 있던 공유 인식을 제공합니다.

0.1.0 릴리스 바이너리 실행에서 캡처된 실제 충돌 필드로 렌더링되었습니다(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
2. Initialize:      foremerge init
3. Wire this client and any others in use: foremerge setup all
4. Register the check I should be validated against, for example:
                    foremerge checks set test -- cargo test --all-targets
5. Confirm:         foremerge doctor --client all

Then read the Foremerge skill that step 3 installed for this client and follow
it from now on: publish your intent with semantic scopes before editing, claim
the scope, and check for conflicts before you start.

4단계를 이 저장소의 실제 테스트 명령어에 맞게 조정하세요. 3단계는 클라이언트가 MCP 서버를 활성화하도록 요청하므로, 수행하기 전에 프롬프트가 표시됩니다. Codex 등록은 사용자 수준이지만 등록 하나로 모든 저장소에 적용됩니다. 조정하려는 저장소 안에서 Codex를 시작하세요.

또는 직접 하기

최신 Git과 jq가 필요합니다. 체크섬 검증된 사전 빌드 릴리스 바이너리를 설치하세요(macOS 및 Linux, 스크립트는 ~/.local/bin에 설치합니다):

curl -fsSL https://foremerge.com/install.sh | sh

[!TIP] 두 개의 명령어, 하나의 프로그램. 이 설치는 foremerge와 fmg를 설치합니다. fmg는 더 짧은 이름의 같은 바이너리이므로, fmg status와 foremerge status는 같은 일을 합니다. 아래 예시는 foremerge로 표기하지만, 원하는 쪽을 입력하면 됩니다.

또는 Rust 1.85+로 소스에서 빌드하세요: cargo install --locked --git https://github.com/naw103/foremerge foremerge, 또는 체크아웃에서 cargo install --locked --path .. Windows 바이너리는 릴리스 페이지에 있습니다. 업데이트하려면 설치 프로그램을 다시 실행하세요. 그리고 조정하려는 저장소 안에서:

foremerge init
foremerge doctor

설치 프로그램, 릴리스 아카이브, cargo install 모두 0.4.0부터 두 이름을 제공합니다. PATH에 이미 fmg라는 다른 프로그램이 있다면, 설치 프로그램은 그것을 가리지 않고 그렇게 알려 줍니다.

이 저장소에서 사용하는 클라이언트를 위해 네이티브 스킬과 MCP 엔트리를 설치한 다음, 에이전트가 이름으로 요청할 수 있는 신뢰된 검사를 정의하세요:

foremerge setup all
foremerge checks set test -- cargo test --all-targets
foremerge doctor --client all

승인은 검증 게이트를 거칩니다. Foremerge는 에이전트의 말을 믿는 대신 검사를 직접 실행합니다. 전체 CI 스위트보다는 빌드나 타입체크처럼 빠르고 실제로 깨진 인계를 잡아낼 수 있는 검사를 선택하세요. 이 게이트는 다른 에이전트가 작업을 완료로 간주해도 되는지를 결정하며 CI를 대체하지 않습니다. 이 저장소에 검증할 의미 있는 항목이 없다면, 항상 통과하는 검사를 등록하는 대신 그 사실을 한 번 말하세요:

foremerge checks policy advisory

그렇게 승인된 작업은 이유와 함께 UNVERIFIED로 기록되므로, 감사 추적에 검사가 실행되지 않았는데 실행된 것처럼 표시되지 않습니다. 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 \
    --no-worktree |
  jq -er '.data.id'
)

STRIPE_RESULT=$(
  foremerge --json intent publish \
    --agent "$STRIPE_AGENT" \
    --task "modernize-payments" \
    --summary "Replace PaymentService with StripePaymentService" \
    --scope symbol:PaymentService=replace
)
STRIPE_INTENT=$(printf '%s\n' "$STRIPE_RESULT" | jq -er '.data.intent.id')

PAYPAL_AGENT=$(
  foremerge --json agent register \
    --name paypal-agent \
    --no-worktree |
  jq -er '.data.id'
)

PAYPAL_RESULT=$(
  foremerge --json intent publish \
    --agent "$PAYPAL_AGENT" \
    --task "add-paypal" \
    --summary "Add PayPal support to PaymentService" \
    --scope symbol:PaymentService=extend
)
PAYPAL_INTENT=$(printf '%s\n' "$PAYPAL_RESULT" | jq -er '.data.intent.id')

printf '%s\n' "$PAYPAL_RESULT" |
  jq '.data.conflicts[] | {kind, severity, scope, explanation, suggestion}'

printf '%s\n' "$PAYPAL_RESULT" |
  jq '.data.related_work[] | {agent, summary, asserted, overlap}'

첫 번째 명령어는 로컬 실행에서 나온 실시간 결과를 출력합니다. 두 번째는 related_work를 출력합니다. 다른 에이전트의 의도와 두 선언된 작업 모두와 겹치는 모든 범위입니다. Foremerge는 무엇이 겹치는지 명시하며, 사용자가 그 의미를 결정하고 foremerge assess record로 기록합니다. 먼저 변경해야 할 파일은 없습니다. 캡처된 명확히 라벨링된 트랜스크립트를 examples/terminal-session.txt에서 확인하세요.

클레임은 어느 에이전트도 차단하지 않으면서 소유 맥락을 추가합니다:

foremerge --json work claim \
  --agent "$STRIPE_AGENT" \
  --intent "$STRIPE_INTENT" \
  --scope symbol:PaymentService \
  --reason "Changing the provider boundary" >/dev/null

foremerge --json work claim \
  --agent "$PAYPAL_AGENT" \
  --intent "$PAYPAL_INTENT" \
  --scope symbol:PaymentService \
  --reason "Adding another provider" |
  jq '.data | {advisory_only, warnings}'

foremerge --json work query --scope symbol:PaymentService |
  jq '.data[] | {agent: .agent.name, intent: .intent.summary, open_conflicts}'

두 클레임 모두 성공합니다. 두 번째 응답에는 겹침 경고가 포함되는데, 클레임은 임대된 권고이지 결코 독점적 소유가 아니기 때문입니다.

Git 위에 어떻게 맞아들어가는가

  coding agent A                                  coding agent B
        |                                               |
  isolated worktree A                            isolated worktree B
        |                                               |
        +--------- semantic events, not edits ----------+
                              |
                    CLI / MCP / JSON API
                              |
                     Foremerge service
                    /        |        \
       SQLite coordination   git CLI   validation argv
       in <git-common-dir>       |           |
                    \         Git repository /
                     durable commits and refs

모든 프런트엔드가 같은 서비스와 저장소를 사용합니다. 의미 그래프는 다음과 같습니다:

Agent → Task → Intent → Claim → Symbol → Dependency
      → ChangeSet → Test → Result → Decision → Provenance

뮤테이션은 타입이 지정된 SQLite 프로젝션을 업데이트하고, 그래프 에지를 구체화하며, 해시 체인으로 연결된 의미 이벤트를 하나의 트랜잭션으로 추가합니다. 로그는 유용한 변조 증거이지만, 원격 신원 서명이나 분산 합의는 아닙니다.

Git 워크트리: 격리된 파일, 공유된 인식

Foremerge는 Git 공통 디렉터리를 확인하고 기본 데이터베이스를 다음 위치에 저장합니다:

<git-common-dir>/foremerge/state.sqlite3

연결된 워크트리는 체크아웃된 파일이 분리되어 있어도 그 공통 디렉터리를 공유합니다. 순수 Git에 대한 Foremerge의 얇은 래퍼로 워크트리를 만드세요:

foremerge worktree create \
  --branch agent/paypal \
  --path ../payments-paypal \
  --base HEAD

foremerge --cwd ../payments-paypal --json agent register \
  --name paypal-agent \
  --model "$ACTUAL_MODEL_ID"

같은 저장소의 다른 워크트리는 등록된 에이전트와 그 의도를 즉시 확인합니다. --database PATH 또는 FOREMERGE_DB로 저장소를 재정의할 수 있지만, 상태를 공유하려면 모든 로컬 에이전트가 같은 데이터베이스를 가리켜야 합니다. MVP는 머신 간에 SQLite를 복제하지 않습니다. 네트워크에 마운트된 데이터베이스에서 분산 안전성을 추론하지 마세요.

Foremerge는 ChangeSet 지문과 승인된 refs를 위해 Git 상태를 스냅샷합니다. 대상 브랜치를 자동으로 merge, rebase, cherry-pick, push하거나 업데이트하지 않습니다.

의미론적 워크플로

INTENT ─claim→ CLAIMED ─start→ IN_PROGRESS ─publish→ PROVISIONAL
       ─validate current fingerprint→ VALIDATED
       ─accept gates→ ACCEPTED ─record Git ref→ COMMITTED

지원되는 범위 종류는 다음과 같습니다:

symbol api schema config infra test migration env file component contract domain

가장 좁은 유용한 의미론적 범위를 게시하세요. 파일 경로만으로는 API, 구성, 스키마, 인프라, 크로스-랭귀지 충돌을 놓칩니다.

일반적인 명령어:

현재 사용 가능한 전체 플래그를 보려면 foremerge <command> --help를 실행하세요. --json, --cwd, --database와 같은 전역 플래그는 하위 명령 앞이나 뒤에 올 수 있습니다.

ChangeSet 및 검증 게이트

ChangeSet은 에이전트/모델, 작업과 의도, 영향받은 파일/심볼/계약, 의존성, 구현 요약, 보고된 테스트, 결정, 출처, 작업 트리, 지문, 상태 및 Git ref를 담습니다. 승인된 후보와 이후의 랜딩 커밋은 accepted_commit 및 integration_commit으로 각각 별도로 보관됩니다.

정직한 통합 순서는 다음과 같습니다.

1. 의도를 게시하고, 의미론적 범위를 클레임하고, 구현이 진행 중임을 표시합니다.

2. 격리된 에이전트 브랜치에서 작업하고 커밋합니다.

3. 해당 깨끗한 후보에 대한 ChangeSet을 게시합니다.

4. Foremerge에게 정확한 지문에 대한 검증 실행을 요청합니다.

5. 높은 충돌을 해결한 다음, 여전히 깨끗하고 검증된 ref를 승인합니다.

6. 일반 Git 또는 풀 리퀘스트로 통합합니다.

7. 영속적인 통합 커밋을 Foremerge에 기록합니다.

foremerge work claim \
  --agent "$AGENT_ID" \
  --intent "$INTENT_ID" \
  --scope component:payments
foremerge work start "$INTENT_ID" --agent "$AGENT_ID"

# Implement the change and commit it on this isolated branch before publishing.
CHANGESET_ID=$(
  foremerge --json changeset publish \
    --agent "$AGENT_ID" \
    --intent "$INTENT_ID" \
    --summary "Introduce PaymentProvider and StripePaymentProvider" \
    --file src/payments.rs \
    --symbol PaymentProvider \
    --symbol StripePaymentProvider \
    --contract payment-provider \
    --provenance-json '{"source":"coding-agent"}' \
    --git-ref HEAD \
    --worktree "$PWD" |
  jq -er '.data.id'
)

foremerge changeset validate "$CHANGESET_ID" \
  --worktree "$PWD" \
  -- cargo test --all-targets

foremerge changeset accept "$CHANGESET_ID" --git-ref HEAD

# Integrate with ordinary Git, then record the commit that actually landed.
foremerge changeset commit "$CHANGESET_ID" --git-ref main

에이전트가 보고한 --reported-test COMMAND=STATUS 값은 출처일 뿐입니다. 이 값은 승인 기준을 충족하지 못합니다. Foremerge 소유의 검증은 명령 인자 벡터, 종료 상태, 출력, 지속 시간, 후보 지문을 기록합니다. 검증 이후 감지된 변경 사항이 있으면 해당 시도는 비권위적이 되지만, 그 출력과 변경 경로 진단은 changeset attempts로 계속 조회할 수 있습니다.

일회용 추적되지 않은 출력을 생성하는 신뢰할 수 있는 검사의 경우, 운영자는 추적된 파일을 변경하지 않고 정확한 경로 또는 디렉터리 접두사 규칙을 설정할 수 있습니다:

foremerge validation-exclusions set \
  --path coverage.log \
  --path target/validation-reports/

정규화된 정책 다이제스트는 후보 지문의 일부이며, 추적된 변경 사항은 절대 제외할 수 없고, MCP는 정책을 변경할 수 없으며, 생성된 파일은 승인 전에 반드시 제거되어야 합니다. ADR 0001을 참조하세요.

승인에는 깨끗한 작업 트리와 해결되지 않은 HIGH 충돌이 없어야 한다는 조건도 있습니다. 단, 호출자가 명시적인 --allow-high-conflicts 재정의를 --override-reason "..."와 함께 의도적으로 사용하는 경우는 예외입니다. 충돌은 명시적인 근거와 함께 해결하는 것이 좋습니다. 승인은 refs/foremerge/accepted/<changeset-id>를 생성하며 코드를 병합하지 않습니다.

검증 명령은 운영 체제 권한을 가진 신뢰할 수 있는 로컬 코드로 실행됩니다. Foremerge는 이들을 샌드박스 처리하지 않습니다.

에이전트 클라이언트 및 MCP: 완전한 수명 주기 도구

stdio를 통해 foremerge mcp를 실행하세요. MCP는 HTTP 데몬이 필요하지 않습니다. 둘 다 동일한 데이터베이스 위의 어댑터입니다.

유효한 최소 구성인 examples/mcp-config.json에서 시작하세요. 이 구성은 클라이언트가 저장소를 작업 디렉터리로 하여 foremerge를 실행한다고 가정합니다. 저장소 작업 디렉터리 설정이 없는 클라이언트는 mcp 앞에 절대 경로의 --database를 전달해야 합니다. 연결된 작업 트리의 .git이 디렉터리라고 가정하지 말고 Git 공통 디렉터리를 파생하세요.

설치 프로그램, 네이티브 스킬 위치, 클라이언트별 MCP 파일, 진단, 안전한 교체 규칙은 에이전트 클라이언트 설정을 참조하세요. 전송 동작, 스키마, 명명된 검사, 예제 입력, 다중 작업 트리 구성은 MCP 설정을 참조하세요.

소스 클론에는 .codex/skills, .claude/skills, .cursor/skills에 동등한 스킬이 포함되어 있으며, 이식 가능한 Claude 및 Cursor MCP 템플릿도 포함됩니다. Cargo 설치에는 표준 스킬이 내장되어 있어 foremerge setup이 이 소스 트리를 복사하지 않고도 다른 저장소에 설치할 수 있습니다.

로컬 JSON API

데몬은 기본적으로 http://127.0.0.1:47811에서 인증된 루프백 HTTP를 사용합니다. init은 플랫폼이 지원하는 경우 비공개 파일 권한으로 베어러 토큰을 생성합니다.

한 터미널에서:

foremerge daemon

다른 터미널에서는 추측하지 말고 Foremerge에서 토큰 경로를 읽으세요:

export FOREMERGE_URL=http://127.0.0.1:47811
TOKEN_FILE=$(foremerge --json init | jq -er '.data.token_file')
FOREMERGE_TOKEN=$(tr -d '\r\n' < "$TOKEN_FILE")

curl --fail --silent --show-error \
  --header "Authorization: Bearer $FOREMERGE_TOKEN" \
  --get "$FOREMERGE_URL/v1/work" \
  --data-urlencode 'scope=symbol:PaymentService' |
  jq .

토큰을 출력하거나 커밋하거나 공유하지 마세요. /healthz는 데이터베이스를 사용하지 않는 프로세스 활성 상태 확인이고, /readyz는 제한된 비대기 저장소 프로브입니다. 둘 다 공개입니다. 페이지네이션된 이벤트 체인 감사를 포함한 모든 /v1 라우트는 토큰을 요구합니다. 단, 신뢰할 수 있는 로컬 테스트를 위해 데몬을 의도적으로 --no-auth로 시작한 경우는 예외입니다. MVP는 루프백이 아닌 바인드를 거부하며, 강화된 멀티 테넌트 서비스가 아닙니다.

CLI 탈출구인 foremerge request는 로컬 인증을 자동으로 읽습니다. 실행 가능한 curl 예제는 examples/api-requests.sh에 있으며, 전체 라우트 및 오류 참조는 JSON API입니다.

MVP가 의도적으로 주장하지 않는 것

• 충돌 탐지는 결정적이고 설명 가능하지만 휴리스틱입니다. 동의어 개념을 놓칠 수 있고 호환 가능한 작업에 대해 경고할 수 있습니다.

• 클레임은 경고만 하며 파일, 심볼 또는 에이전트를 절대 잠그지 않습니다.

• 검증 통과는 기록된 명령이 기록된 지문에 대해 통과했다는 것만 증명하며, 테스트 계획이 완전했음을 증명하지 않습니다.

• Git ref와 프로세스 결과는 자체 보고된 모델, 프롬프트 또는 테스트 설명보다 더 강력한 증거입니다.

• 이벤트 체인은 보존된 체인 내부의 변경 사항을 감지합니다. 서명, 원격 증명 또는 외부 체크포인트가 아닙니다.

• 로컬 SQLite는 공유 모드 합의가 아니며, 루프백 베어러 토큰은 공개 배포 보안 모델이 아닙니다.

• 실행 가능한 벤치마크 픽스처, 재현 가능한 쿼리 하네스, 벤치마크 계획이 있지만 아직 게시된 조정 대 비조정 성능 결과는 없습니다.

• Foremerge는 코드 리뷰, 아키텍처 소유권, CI, 보안 스캐닝, Git 호스팅 규칙 또는 백업을 대체하지 않습니다.

Foremerge를 통합 게이트로 사용하기 전에 전체 제한 사항 및 신뢰 모델을 읽으세요.

문서

또한 변경 로그, 보안 정책, 행동 강령을 참조하세요.

기여 및 라이선스

기여를 환영합니다. 특히 범위 어휘, 충돌 증거, ChangeSet 출처, 검증 정책에 대한 프로토콜 피드백을 환영합니다. CONTRIBUTING.md를 읽은 후 전체 로컬 게이트를 실행하세요:

make verify

Foremerge는 Apache License 2.0에 따라 라이선스가 부여됩니다.