Foremerge

Foremerge es el protocolo de coordinación de código abierto para agentes de codificación, construido sobre Git. Los agentes mantienen árboles de trabajo aislados mientras comparten intención, afirmaciones semánticas, dependencias, ChangeSets provisionales, decisiones, validación y procedencia.

Estado: Foremerge 0.4.0 es un MVP pre-1.0, local-first. El CLI, la API JSON, el servidor MCP, el almacén SQLite, el detector de conflictos determinista y el ciclo de vida con verificación están implementados. Los esquemas públicos pueden cambiar. El modo compartido multi-máquina y los resultados de referencia publicados aún no existen.

Cómo funciona

Supongamos que tienes dos agentes de IA trabajando en el mismo proyecto al mismo tiempo. Cada uno obtiene su propia copia del código, por lo que nunca pelean por los archivos. Ambos terminan. Ambos parecen correctos. Luego descubres que deshicieron el trabajo del otro.

Git no puede advertirte sobre eso, porque Git compara texto y no intención. Te detendrá cuando dos agentes editen la misma parte del mismo archivo. Lo que no puede ver son dos ediciones que son cada una perfectamente razonables por sí solas y que aterrizan en archivos diferentes. Si un agente mueve a todos los llamadores a un nuevo StripePaymentService mientras otro agrega soporte de PayPal al antiguo PaymentService, nada se superpone, por lo que Git fusiona ambos sin quejarse y el trabajo de PayPal queda varado en una clase que ya nadie llama.

Foremerge soluciona esto haciendo que los agentes anuncien lo que están a punto de hacer, antes de hacerlo.

1. Cada agente dice lo que está a punto de tocar. No el código, solo el objetivo, como "voy a cambiar la función sendEmail".

2. Cada agente lee de una lista compartida. Es una pequeña base de datos dentro de la carpeta .git de tu proyecto, por lo que cada agente en tu máquina ve la misma imagen, ya sea Claude, Codex o Cursor.

3. Si dos planes chocan, te enteras de inmediato. Foremerge nombra a los dos agentes, explica por qué sus planes chocan y sugiere cómo dividir el trabajo. Ambos árboles de trabajo siguen limpios en ese punto, por lo que no hay que tirar ningún trabajo.

Piénsalo como una pizarra compartida. Antes de que un agente comience, escribe en qué va a trabajar y lee lo que todos los demás ya escribieron.

Dos cosas que Foremerge deliberadamente no hace. Nunca bloquea un archivo ni bloquea a un agente, porque un solo agente bloqueado detendría a toda la flota, por lo que las advertencias son de asesoramiento y tú sigues al mando. Y nunca pide a un modelo que juzgue conflictos, por lo que las mismas entradas siempre producen la misma respuesta.

Related MCP server: batuta-mcp

El conflicto que Git aún no puede ver

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

Estos agentes pueden trabajar en árboles diferentes sin tocar la misma línea. Los planes aún chocan: uno elimina el punto de extensión mientras el otro depende de él.

Ambos agentes declaran el mismo ámbito symbol:PaymentService, uno diciendo que lo reemplazará y el otro que lo extenderá. Foremerge compara esas dos declaraciones antes de que cualquiera escriba código, genera un aviso de ALTO y sugiere coordinar sobre una abstracción estable como PaymentProvider. Esa sugerencia es evidencia explicable, no una decisión automática de arquitectura ni un bloqueo duro.

Debido a que la operación se declara en lugar de leerse del resumen, no importa cómo cada agente haya formulado su plan. "Consolidar pagos en Stripe" y "Reemplazar PaymentService con Stripe" llegan al mismo veredicto.

Git sigue siendo el repositorio duradero. Foremerge proporciona la conciencia compartida que falta por encima de él.

Renderizado a partir de los campos de conflicto reales capturados por la ejecución del binario de lanzamiento 0.1.0 en examples/terminal-session.txt. El comando mostrado usa el filtro jq indicado; la salida está abreviada para facilitar la lectura.

Inicio rápido: primer conflicto en menos de cinco minutos

Deja que tu agente de codificación lo haga

Pega esto en Claude Code, Codex o Cursor desde dentro del repositorio que quieras coordinar:

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.

Ajusta el paso 4 al comando de prueba real de este repositorio. El paso 3 pide al cliente que habilite un servidor MCP, por lo que te pedirá confirmación antes de hacerlo. El registro de Codex es a nivel de usuario, pero un solo registro sirve para todos los repositorios: inicia Codex dentro del repositorio que quieras coordinar.

O hazlo tú mismo

Necesitas un Git reciente y jq. Instala un binario de lanzamiento precompilado y verificado por checksum (macOS y Linux; el script instala en ~/.local/bin):

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

[!TIP] Dos comandos, un programa. Esto instala foremerge y fmg, el mismo binario con un nombre más corto, por lo que fmg status y foremerge status hacen lo mismo. Los ejemplos a continuación escriben foremerge; escribe el que prefieras.

O compila desde el código fuente con Rust 1.85+: cargo install --locked --git https://github.com/naw103/foremerge foremerge, o cargo install --locked --path . desde un checkout. Los binarios de Windows están en la página de lanzamientos. Para actualizar, vuelve a ejecutar el instalador. Luego, dentro del repositorio que quieras coordinar:

foremerge init
foremerge doctor

El instalador, los archivos de lanzamiento y cargo install llevan ambos nombres desde 0.4.0 en adelante. Si algo más en tu PATH ya responde a fmg, el instalador lo deja en paz y lo dice en lugar de ocultarlo.

Instala la skill nativa y la entrada MCP para cualquier cliente utilizado en este repositorio, luego define los checks de confianza que los agentes pueden solicitar por nombre:

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

La aceptación está controlada por verificación: Foremerge ejecuta el check por sí mismo en lugar de tomar la palabra del agente. Elige un check que sea rápido y que realmente detecte un traspaso roto, como una compilación o un typecheck, en lugar de una suite de CI completa; esta puerta decide si otros agentes pueden tratar el trabajo como hecho, y no reemplaza a CI. Si este repositorio no tiene nada significativo que verificar, dilo una vez en lugar de registrar un check que siempre pasa:

foremerge checks policy advisory

El trabajo aceptado de esa manera se registra como UNVERIFIED con el motivo, por lo que el rastro de auditoría nunca implica que se ejecutó un check cuando no fue así. foremerge doctor informa si los checks registrados pueden ejecutarse realmente aquí, lo cual importa en los árboles de trabajo de agentes, porque los directorios de dependencias suelen estar en gitignore y git worktree add no los creará.

Usa setup codex, setup claude o setup cursor para un cliente. La configuración preserva la configuración no relacionada (incluido el orden de las claves en el JSON MCP del proyecto). Actualizar Foremerge refresca su propio archivo de skill sin editar en su lugar, pero un archivo de skill que hayas editado, o una entrada MCP de Foremerge diferente, nunca se reemplaza a menos que pases explícitamente --force. setup all intenta cada cliente e informa cada resultado, saliendo con código distinto de cero si alguno falla. El registro MCP de Codex es a nivel de usuario y sirve para todos los repositorios, resuelto desde el directorio en el que se inicia Codex; consulta configuración de clientes de agentes.

init crea el estado de coordinación local bajo el directorio común de Git del repositorio. No cambia archivos rastreados. Las siguientes sesiones sin árbol de trabajo son suficientes para ejercitar la detección previa al código; los agentes de codificación reales deben registrar sus árboles de trabajo aislados y sus identificadores de modelo reales.

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}'

El primer comando imprime el hallazgo en vivo de tu ejecución local. El segundo imprime related_work: la intención del otro agente y cada ámbito superpuesto con ambas operaciones declaradas. Foremerge declara qué se superpone; tú decides qué significa y lo registras con foremerge assess record. No es necesario que cambien archivos primero. Inspecciona la transcripción capturada y claramente etiquetada en examples/terminal-session.txt.

Las afirmaciones agregan contexto de propiedad sin bloquear a ninguno de los agentes:

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}'

Ambas afirmaciones tienen éxito. La segunda respuesta incluye una advertencia de superposición porque una afirmación es un aviso arrendado, nunca propiedad exclusiva.

Cómo encaja por encima de 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

Cada frontend usa el mismo servicio y almacén. El grafo semántico es:

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

Las mutaciones actualizan proyecciones SQLite tipadas, materializan aristas del grafo y agregan un evento semántico encadenado por hash en una sola transacción. El registro es evidencia útil de manipulación; no es una firma de identidad remota ni consenso distribuido.

Árboles de trabajo de Git: archivos aislados, conciencia compartida

Foremerge resuelve el directorio común de Git y almacena su base de datos predeterminada en:

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

Los árboles de trabajo vinculados comparten ese directorio común aunque sus archivos de checkout estén separados. Crea un árbol de trabajo con el envoltorio ligero de Foremerge alrededor de Git estándar:

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"

Otro árbol de trabajo en el mismo repositorio ve al agente registrado y sus intenciones de inmediato. Puedes anular el almacenamiento con --database PATH o FOREMERGE_DB, pero cada agente local debe apuntar a la misma base de datos para compartir estado. El MVP no replica SQLite entre máquinas; no infieras seguridad distribuida de una base de datos montada en red.

Foremerge captura el estado de Git para huellas de ChangeSet y refs aceptados. No fusiona, rebasea, cherry-pickea, empuja ni actualiza una rama objetivo automáticamente.

Flujo de trabajo semántico

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

Los tipos de ámbito admitidos son:

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

Publica el ámbito semántico más estrecho y útil. Las rutas de archivo por sí solas pierden colisiones de API, configuración, esquema, infraestructura y entre lenguajes.

Comandos comunes:

Ejecuta foremerge <command> --help para ver todas las banderas actuales. Las banderas globales como --json, --cwd y --database pueden aparecer antes o después de los subcomandos.

ChangeSets y la puerta de verificación

Un ChangeSet captura el agente/modelo, la tarea y la intención, los archivos/símbolos/contratos afectados, las dependencias, el resumen de implementación, las pruebas notificadas, las decisiones, la procedencia, el worktree, la huella digital, el estado y la referencia de Git. El candidato aceptado y su posterior commit de integración se conservan por separado como accepted_commit e integration_commit.

El orden de integración honesto es:

1. Publica la intención, reclama el alcance semántico y marca la implementación como en curso.

2. Trabaja y haz commit en la rama aislada del agente.

3. Publica un ChangeSet para ese candidato limpio.

4. Pide a Foremerge que ejecute la validación contra su huella digital exacta.

5. Resuelve los conflictos altos y luego acepta la referencia aún limpia y aún validada.

6. Integra con Git ordinario o con una pull request.

7. Registra el commit de integración duradero en 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

Los valores de --reported-test COMMAND=STATUS notificados por el agente son solo procedencia. No satisfacen la aceptación. La validación propiedad de Foremerge registra el vector de argumentos del comando, el estado de salida, la salida, la duración y la huella digital del candidato. Cualquier cambio detectado después de la validación hace que ese intento no sea autoritativo, pero su salida y el diagnóstico de rutas modificadas siguen siendo consultables con changeset attempts.

Para comprobaciones de confianza que generan salida no rastreada desechable, un operador puede establecer reglas exactas o de prefijo de directorio sin cambiar los archivos rastreados:

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

El resumen de política normalizado forma parte de la huella digital del candidato, los cambios rastreados nunca se pueden excluir, MCP no puede cambiar la política, y los archivos generados deben eliminarse antes de la aceptación. Véase ADR 0001.

La aceptación también requiere un worktree limpio y ningún conflicto HIGH sin resolver, a menos que quien llama use deliberadamente la anulación visible --allow-high-conflicts junto con --override-reason "...". Prefiere resolver un conflicto con una justificación explícita. La aceptación crea refs/foremerge/accepted/<changeset-id>; no fusiona código.

Los comandos de validación se ejecutan como código local de confianza con los permisos de tu sistema operativo. Foremerge no los aísla en una sandbox.

Clientes de agente y MCP: herramientas completas del ciclo de vida

Ejecuta foremerge mcp sobre stdio. MCP no requiere el daemon HTTP; ambos son adaptadores sobre la misma base de datos.

Parte de la configuración mínima válida en examples/mcp-config.json. Asume que el cliente lanza foremerge con el repositorio como su directorio de trabajo. Los clientes sin una configuración de directorio de trabajo de repositorio deben pasar un --database absoluto antes de mcp; deriva el directorio común de Git en lugar de asumir que el .git de un worktree vinculado es un directorio.

Consulta configuración de clientes de agente para el instalador, las ubicaciones nativas de skills, los archivos MCP específicos del cliente, el diagnóstico y las reglas seguras de reemplazo. Consulta configuración de MCP para el comportamiento del transporte, esquemas, comprobaciones con nombre, ejemplos de entrada y configuración multi-worktree.

Los clones de la fuente incluyen skills equivalentes en .codex/skills, .claude/skills y .cursor/skills, además de plantillas MCP portátiles para Claude y Cursor. Una instalación de Cargo incorpora la skill canónica para que foremerge setup pueda instalarla en otro repositorio sin copiar este árbol fuente.

API JSON local

El daemon usa por defecto HTTP de loopback autenticado en http://127.0.0.1:47811. init crea un token de portador con permisos de archivo privados donde la plataforma los admite.

En una terminal:

foremerge daemon

En otra terminal, lee la ruta del token desde Foremerge en lugar de adivinarla:

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 .

No imprimas, hagas commit ni compartas el token. /healthz es una comprobación de actividad del proceso sin base de datos y /readyz es una sonda acotada y no bloqueante del almacén; ambos son públicos. Cada ruta /v1, incluida la auditoría paginada de la cadena de eventos, requiere el token a menos que el daemon se haya iniciado deliberadamente con --no-auth para una prueba local de confianza. El MVP rechaza enlaces que no sean loopback y no es un servicio multiusuario reforzado.

La vía de escape de la CLI foremerge request lee la autenticación local automáticamente. Hay un tutorial ejecutable con curl en examples/api-requests.sh; la referencia completa de rutas y errores es API JSON.

Lo que el MVP deliberadamente no afirma

• La detección de conflictos es determinista y explicable, pero heurística. Puede pasar por alto conceptos sinónimos y avisar sobre trabajo compatible.

• Los reclamos advierten; nunca bloquean archivos, símbolos ni agentes.

• Superar la validación solo demuestra que el comando registrado pasó para la huella digital registrada, no que el plan de pruebas estaba completo.

• Las referencias de Git y los resultados de los procesos son evidencia más sólida que el modelo, el prompt o la prosa de pruebas autoinformados.

• La cadena de eventos detecta cambios dentro de la cadena conservada; no es una firma, una atestación remota ni un punto de control externo.

• El SQLite local no es consenso en modo compartido, y el token de portador de loopback no es un modelo de seguridad para despliegues públicos.

• Existen fixtures de benchmark ejecutables, un arnés de consultas reproducible y un plan de benchmark, pero aún no hay resultados de rendimiento publicados que comparen coordinado vs. no coordinado.

• Foremerge no reemplaza la revisión de código, la propiedad de la arquitectura, la CI, el escaneo de seguridad, las reglas de alojamiento de Git ni las copias de seguridad.

Lee el modelo de limitaciones y confianza completo antes de usar Foremerge como puerta de integración.

Documentación

Consulte también el changelog, la política de seguridad y el código de conducta.

Contribución y licencia

Las contribuciones son bienvenidas, especialmente la retroalimentación sobre el protocolo en el vocabulario de alcance, la evidencia de conflictos, la procedencia de ChangeSet y la política de verificación. Lee CONTRIBUTING.md y, a continuación, ejecuta el gate local completo:

make verify

Foremerge se distribuye bajo la Apache License 2.0.