Foremerge

Foremerge — это открытый протокол координации для программирующих агентов, построенный поверх Git. Агенты работают в изолированных worktree, обмениваясь намерениями, семантическими утверждениями, зависимостями, предварительными ChangeSets, решениями, результатами проверки и происхождением данных.

Статус: Foremerge 0.4.0 — это локально-ориентированный MVP до версии 1.0. Реализованы CLI, JSON API, MCP-сервер, хранилище SQLite, детерминированный детектор конфиктов и жизненый цикл, контролируемый проверкой. Публичные схемы могут ещё менятся. Режим совместной работи на нескольких машинах и опубликованные результати бенчмарков пока отсуствуют.

Как это работает

Представьте, что два ИИ-агента одновремено работоют над одним проектом. Каждый получает собственную копию кода, поэтому они не конфликтую за файлы. Оба завершаут работу. Оба выглядят корректно. А затем вы обнарживаете, что они отменили работу друг друга.

Git не может предупредить вас об этом, потому что Git сравнивает текст, а не намерения. Он остановит вас, когда два агента редактируют одну и ту же часть одного и того же файла. Но он не видит две правки, каждая из которых сама по себе совершенно разумна, но вносится в разные файлы. Если один агент переводит всех вызывающих на новый StripePaymentService, а другой добавляет поддержку PayPal в старый PaymentService, ничто не пересекается, поэтому Git без возражений объединяет оба изменения, и работа с PayPal оказывается на классе, который больше никто не вызывает.

Foremerge решает эту проблему, заставляя агентов объявлять о том, что они собираются сделать, до того как это сделают.

1. Каждый агент сообщает, к чему собирается прикоснуться. Не код, а только цель, например: «Я собираюсь изменить функцию sendEmail».

2. Каждый агент читает один общий список. Это небольшая база данных внутри папки .git вашего проекта, поэтому каждый агент на вашей машине видит одну и ту же картину — будь то Claude, Codex или Cursor.

3. Если два плана сталкиваются, вы узнаёте об этом немедленно. Foremerge называет обоих агентов, объяснят, почему их планы противоречат друг другу, и предлгает, как разделить работу. Оба worktree в этот момент ещё чисты, так что ни какую работу выбрасывать не придётся.

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

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

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; выввод сокращён для удобочитаемости.

Быстрый старт: первый конфликт менее чем за пять минут

Пусть это сделает ваш агент

Вставьте это в 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 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 сообщает, могут ли зарегистрированные проверки реально запускаться здесь; это важно в агентских worktree, потому что каталоги зависимостей обычно игнорируются Git, и git worktree add не создаёт их.

Используйте setup codex, setup claude или setup cursor для одного клиента. Setup сохраняет постороннюю конфигурацию (включая порядок ключей в проекном MCP JSON). При обновлении Foremerge обновляет на месте свой собственный неотредактированный файл навыка, но файл навыка, который вы редактировали, или отличающаяся MCP-запись Foremerge не заменяются, если вы явно не передадите --force. setup all пробует каждого клиента и сообщает результат по каждому, завершаясь с ненулевым кодом, если что-то не удалось. Регистрация MCP для Codex выполняется на уровне пользователя и обслуживает все репозитории, определяясь по каталогу, из которого запущен Codex; см. настройка агентских клиентов.

init создаёт локальное состояние координации в общем каталоге Git репозитория. Он не меняет отслеживаемые файлы. Приведённых ниже сессий без worktree достаточно, чтобы опробовать обнаружение до написания кода; настоящие код-агенты должны регистрировать свои изолированные 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 worktree: изолированные файлы, общая осведомлённость

Foremerge определяет общий каталог Git и хранит свою базу данных по умолчанию в:

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

Связнные worktree разделяют этот общий каталог, хотя их извлечённые файлы раздельны. Создайте worktree с помощью тонкой обёртки Foremerge вокруг стандортного Git:

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"

Друго worktree в том же репозитории сразу видит зарегистрированного агента и его намерения. Вы можете переопределить хранилище с помощью --database PATH или FOREMERGE_DB, но каждый локальный агент должен указывать на одну и ту же базу данных, чтобы обмениваться состоянием. MVP не реплицирует SQLite между машинами; не делайте выводов о распределённой безопасности на основе базы данных, смонтированной по сети.

Foremerge создаёт снимки состояния Git для отпечатков ChangeSet и принятых ссылок (refs). Он не выполняет автоматически 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, могут указываться до или после подкоманд.

ChangeSets и шлюз проверки

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

Добросовестный порядок интеграции:

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

2. Работайте и коммитьте в изолированной ветке агента.

3. Опубликуйте ChangeSet для этого чистого кандидата.

4. Попросите Foremerge выполнить проверку по его точному отпечатку.

5. Разрешите конфликты уровня HIGH, затем примите по-прежнему чистую и по-прежнему проверенную ссылку.

6. Выполните интеграцию обычным Git или через pull request.

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: полный набор инструментов жизненного цикла

Запускайте foremerge mcp через stdio. MCP не требует HTTP-демона; оба они являются адаптерами поверх одной и той же базы данных.

Начните с допустимой минимальной конфигурации в examples/mcp-config.json. Предполагается, что клиент запускает foremerge с репозиторием в качестве рабочего каталога. Клиенты без настройки рабочего каталога репозитория должны передавать абсолютный путь --database перед mcp; определяйте общий каталог Git, а не предполагайте, что .git связанного рабочего дерева является каталогом.

См. настройку клиента агента — там описаны установщик, расположение нативных навыков, файлы MCP для конкретных клиентов, диагностика и правила безопасной замены. См. настройку MCP — там описаны поведение транспорта, схемы, именованные проверки, примеры входных данных и конфигурация с несколькими рабочими деревьями.

Клоны исходного репозитория содержат эквивалентные навыки в .codex/skills, .claude/skills и .cursor/skills, а также переносимые шаблоны MCP для Claude и Cursor. Установка через Cargo встраивает канонический навык, поэтому foremerge setup может установить его в другой репозиторий без копирования этого дерева исходников.

Локальный JSON API

Демон по умолчанию слушает аутентифицированный loopback-HTTP на http://127.0.0.1:47811. init создаёт bearer-токен с приватными правами доступа к файлу там, где это поддерживает платформа.

В одном терминале:

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 не разрешает привязку к адресам, отличным от loopback, и не является защищённой моделью безопасности для публичного развёртывания.

Команда foremerge request — это запасной выход CLI; она автоматически считывает локальную аутентификацию. Выполняемый пример с curl находится в examples/api-requests.sh; полный справочник маршрутов и ошибок — JSON API.

Что MVP намеренно не заявляет

• Обнаружение конфликтов детерминировано и объяснимо, но эвристично. Оно может пропускать синонимичные понятия и предупреждать о совместимой работе.

• Заявки предупреждают; они никогда не блокируют файлы, символы или агентов.

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

• Git-ссылки и результаты процессов — более веские доказательства, чем самостоятельно сообщённые модель, промпт или текст тестов.

• Цепочка событий обнаруживает изменения внутри сохраняемой цепочки; она не является подписью, удалённой аттестацией или внешней контрольной точкой.

• Локальный SQLite — это не консенсус в режиме совместного доступа, а loopback bearer-токен — не модель безопасности для публичного развёртывания.

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

• Foremerge не заменяет ревью кода, ответственность за архитектуру, CI, сканирование безопасности, правила хостинга Git или резервное копирование.

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

Документация

Также см. журнал изменений, политику безопасности и кодекс поведения.

Вклад и лицензия

Вклад приветствуется, особенно обратная связь по протоколу о словаре области, доказателаствах конфликтов, происхождении ChangeSet и политике верификации. Прочтите CONTRIBUTING.md, а затем запустите полную локальную проверку:

make verify

Foremerge распространяется под лицензией Apache License 2.0.