agentclaim

Múltiples agentes. Un único árbol de trabajo. Git no te salvará.

Propiedad de archivos para agentes de codificación de IA en paralelo, para que dejen de sobrescribirse entre sí en silencio.

npm i -g agentclaim && agentclaim init

El problema

Ejecutas dos, tres o cinco agentes de codificación a la vez. Comparten un único árbol de trabajo.

Git se construyó para personas en clones separados que fusionan más tarde. No tiene idea de qué hacer con dos escritores editando el mismo checkout al mismo segundo. No hay marcador de conflicto, ni aviso, ni fusión: la segunda escritura simplemente gana y la primera desaparece.

Estos son tres incidentes reales de una tarde en un único repositorio. Los tres llegaron a producción. Ninguno generó un solo mensaje de error.

1. La carrera de staging

git add captura una instantánea de un archivo tal como está en ese instante.

 session A            session B
 ─────────            ─────────
                      git add i18n.js Money.jsx   ← snapshots i18n.js v1
 write i18n.js v2
                      git commit                  ← commit contains i18n.js v1

El commit incluyó un nuevo Money.jsx junto al antiguo i18n.js. La pantalla mostró claves de traducción en bruto en producción. Git informó de éxito. El commit de corrección posterior cayó en exactamente la misma carrera.

2. La restauración destructiva

git checkout HEAD -- i18n.js api.demo.js   # session A tidies its tree
git commit -a                              # session B, two seconds later

El trabajo de la sesión B se revirtió del disco y luego se confirmó en un commit. En silencio.

3. El control que mintió

El script de despliegue tenía un guard contra árbol sucio. Comprobaba el árbol en el momento del despliegue, no la carrera en el momento del commit. El control se puso en verde, el commit era incorrecto y el despliegue publicó fielmente el commit equivocado.

Related MCP server: asynkor

La solución

Las escrituras se vuelven más inteligentes. Los commits siguen siendo estrictos.

Bloquear a cada segundo escritor no sería más que una señal de stop, no una solución; y una herramienta que bloquea trabajo que la gente necesita hacer se acaba desactivando. Dos agentes en un mismo archivo solo están en conflicto real cuando tocan la misma región.

Por eso agentclaim no pregunta «¿quién es el dueño de este archivo?». Pregunta «¿qué ha cambiado desde la última vez que lo miré?», la única pregunta que separa las ediciones del otro agente de las tuyas. Si las regiones son distintas, ambos agentes siguen trabajando; si son las mismas líneas, uno se detiene.

agentclaim: src/checkout.ts is also being edited by another agent — your edits do not overlap theirs.
  their lines: 12-19
  your lines:  84-91
Both edits are kept. You may not commit this file until they are done.

Un Write completo del archivo tampoco es un conflicto: se fusiona a tres bandas con el trabajo del otro agente mediante git merge-file, de modo que ambas ediciones quedan incluidas:

agentclaim: src/checkout.ts was merged, not overwritten.
Another agent had edited this file; your write has been combined with
their changes. Re-read the file before continuing — it now contains both.

Las líneas superpuestas tampoco son una señal de stop

Una edición dirigida es quirúrgica: solo se aplica si su texto de ancla sigue existiendo en el archivo tal como está ahora. Esa única propiedad lo hace todo.

• el ancla sigue ahí → reemplazarla conserva las ediciones del otro agente, porque sus cambios están, por definición, en otro lugar del texto

• el ancla ya no está → la herramientar reclaza por sí misma y el agente vuelve a leer

De cualquier manera, el resultado ya es correcto, así que bloquear costaría un viaje de ida y vuelta y no aportaría nada. agentclaim añade contexto en su lugar:

agentclaim: heads up — another agent just changed the same lines of src/checkout.ts.
  their lines: 12-19
  your lines:  14-16

Your edit still applies cleanly on top of their version. This is what
they changed, in case it affects what you were about to do:
  @@ line 12-19 @@
  -  const total = items.length
  +  const total = items.reduce((n, i) => n + i.qty, 0)

Nothing is blocked. You may not commit this file until they are done.

Lo que realmente detiene a un agente

Cuatro cosas, y solo estas:

Nada en la ruta de edición se detiene. A pure: insists: **Una herramienta que interrumpe a los agentes mientras hacen trabajo normal se desactiva, y entonces no protege nada. Ese es el punto.

Los commits son la parte estricta

Una vez que dos sesiones activas han tocado un archivo, ninguna puede ponerlo en staging ni hacer commit de él: es exactamente así como un agente publica el trabajo del otro, como el Incidente #1 anterior.

Esa protección sería un punto muerto si no tuviera salida; por eso tiene tres:

Las sésiones terminar o cae dejan libo todo lo que mantienen, así que el árbol nunca queda bloqueado.

Ted ningún servidor. Ningún demonios. Sin dependencias. El almacén de reservas es un directorio dentro de .git/.

Inicio rápido

npm i -g agentclaim
cd your-repo
agentclaim init

¿Prefieres no instalarlo globalmente? npx agentclaim init funciona también: primero se copia a sí mismo a ~/.agentclaim/lib, porque los hooks deben apuntar a un ruta que siga existiendo mañana.

Eso es todo. init configura los hooks de Claude Code e instala un hook pre-commit de git (encadenando cualquier hook que existan). Comprúebalo en cualquier momento:

$ agentclaim status
SESSION          FILES  AGE   LAST SEEN
● money screen       3  6m    2s
  ai visibility      2  22m   14s

FILE                    HELD BY        AGE
web/src/Money.jsx       (you)          6m
web/src/i18n.jsx        (you)          6m
web/src/api.demo.js     ai visibility  22m

Da a tu sesioón un nombre legible para que el mensaje de error del otro agente signifique algo:

agentclaim label "money screen"

Qué cambia init en tu máquina

Tres cosas. Nada más.

no llamar no hace llamadas de red. No telemetría. No procesos de fondo. No se toca ni una línea de tu código y no parece nada nuevo en git status.

No hace nada cuando estás solo

Si en el árbol solo tu sesión está activa, todos los controles se cortocan en pasado para permitir. No se aplica ninguna reserva, no se inspecciona ningún comando, no hay nada que saltar.

Esto es deliberado. Un control que la gente no puede pasar es peor que no tener control, porque se aprende a desactivarlo y deja de proteger nada. In fact, agentclaim solo tiene dientes in the exact situation que existe.

$ agentclaim doctor
...
1 live session(s) · 3 claim(s) · TTL 30m · mode block
single session -> gates inactive (no-op)

Los cuatro controles

<| # | Control | Cuándo | Qué detiene | | - | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | | 1 | Escritura | antes de Write / Edit | nada en la ruta de edición: las escrituras completas se fusionan y solo una infusiónable y no fusionable deten | | 2 | Git | antes de un comando Bash | git add -A, git commit -a, git checkout -- x, git reset --hard, git stash, git clean que tocan archivos que no te pertenecen | | 3 | Verdad delcommit | después de git commit | la carrera de la instantánea: contenido del commit que no coincide con el tiempo | | 4 | pre-commit | en cualquier git commit | archivos ens staging cuya dueña es otra persona, desde cualquier tool |

El Control 3 es el que nada más detecta. Vuelve a leer cada ruta del commit con git show <sha>:<path> y la compare byte a byte con el archivo en disco:

agentclaim: ⚠ commit 045d1f7 does NOT match what is on disk:
  web/src/api.demo.js

This is the classic `git add` snapshot race: another session rewrote these
files after you staged them, so the commit captured stale content.
DO NOT DEPLOY. Fix it with:
  git add web/src/api.demo.js && git commit --amend --no-edit

Solo informa sobre archivos que están en manos de otro una sesión, de modo que el staging parcial ordinario (git add x, seguir editando x, commit) nunca haga cautiva una falsa alarma.

Compatible con cualquier agente

Tres capas de integración, de la más potente a la más ligera. Usa tantas como se adapten.

Claude Code - hooks (la más potente)

agentclaim init            # project-level  (.claude/settings.json)
agentclaim init --global   # every repo     (~/.claude/settings.json)

Los gates se ejecutan antes de la escritura o del comando. El agente recibe como respuesta el rechazo y elige otro archivo por sí mismo.

Cursor · Windsurf · Codex · Zed · Cline · cualquier MCP

agentclaim includes un servidor MCP, así que any agente of speaking MCP puede participating in the same protocolo de propiedad:

{
  "mcpServers": {
    "agentclaim": {
      "command": "agentclaim",
      "args": ["mcp"],
      "env": { "AGENTCLAIM_SESSION": "cursor-1", "AGENTCLAIM_AGENT": "cursor" }
    }
  }
}

Herramientas expuestas: agentclaim_status, agentclaim_claim, agentclaim_release, agentclaim_check, agentclaim_verify_commit. The descripciones le dicen al modelo cuándo imitar a.

Todo lo demás: el hook de git

agentclaim init instala un hook pre-commit, de modo que aider, un git commit simple, tu IDE o un script shell usan la misma comprobación. No hay nada que configurar.

Para scripts de despliegue y CI, usa el control de código de salida:

agentclaim check --staged --quiet || exit 1   # anyone else holding staged files?
agentclaim verify HEAD                        # did the commit capture disk?

Comandos

agentclaim init [--global]    wire up the hooks (Claude Code + git pre-commit)
agentclaim status             who holds what
agentclaim who <path>         owner of a single file
agentclaim claim <path...>    claim files            [--note "..."]
agentclaim release <path...>  "I am done here"       [--all] [--force to take over]
agentclaim check <path...>    gate for scripts, exit 0/1  [--staged] [--quiet]
agentclaim verify [rev]       compare commit content against disk  [--all]
agentclaim label "<name>"     give this session a readable name
agentclaim gc                 collect stale claims
agentclaim doctor             diagnose the installation
agentclaim uninstall          remove the hooks
agentclaim mcp                run as an MCP server

Configuración

create .agentclaim.json opcional en la raíz del repo:

{
  "ttlMinutes": 30,
  "touchTtlMinutes": 10,
  "mode": "block",
  "ignore": ["node_modules/**", "dist/**", "*.lock", "package-lock.json"]
}

• ttlSeconds — una sesión que lleva este tiempo sin actividad se considera muerta y sus requisitos pueden adoptar. Cada invocación demuestra el latido, así que una sesión activa expira.

• touchTtlMinutes — cuánto tiempo una sesión sigue bloqueando a otras para hacer commit de un archivo después de su último there. Es más corto que ttlSeconds a propósito: sigue viva no es lo mismo que seguir trabajando in this file, and confundir ambos es lo que convierte protección en interbloqueo.

• mode — block (por defecto), warn (notifica pero permite), off.

• ignore — nunca claims. Pon aquí los archivos generados; si los lockfiles y la salida de build se reivindican, el gate se dispara permanentmente y la gente empieza a salarse.

##Cómo funciona

.git/agentclaim/
  sessions/<id>.json   { sid, label, pid, started, seen, wt }
  claims/<hash>.json   { path, wt, sid, at, touchers }
  snap/<sid>/<hash>    what that session last saw on disk
  pending/<sid>/<hash> a merge computed before a write, applied right after it
  pass.json            short-lived identity token for the git hook

• Ubicación de almacenamiento es git rev-parse --git-common-dir, por lo que cada worktree del repositorio comparte un único registro.

• Claves de reclamación incluyen la raíz del worktree, porque la misma ruta relativa en dos worktrees son dos archivos diferentes en disco. Los worktrees separados nunca se bloquean entre sí — son una solución legítima para este problema, no algo que deba castigarse.

• Atomicidad es open(..., 'wx') — O_EXCL. Dos reclamaciones simultáneas, un ganador, sin condiciones de carrera.

• Liveness se basa en TTL. Los hooks se ejecutan en cada llamada a una herramienta, por lo que seen permanece reciente en cuestión de segundos; las reclamaciones de un agente caído son recuperables y nunca bloquean el repositorio.

• Razonamiento de regiones compara la instantánea de tu sesión con el archivo en disco usando git diff --no-index -U0, y fusiona con git merge-file. Todo es la semántica propia de git — esa en la que ya confías — sin dependencia añadida.

• Las fusiones las aplicamos nosotros, no se inyectan. El esquema de salida del hook tiene un campo updatedInput, pero nada verificable dice que se aplique sin aprobar también automáticamente la llamada, y una suposición errónea ahí descartaría silenciosamente el trabajo del otro agente. Así que la fusión se guarda y se escribe justo después de que la herramienta se ejecute, usando solo mecanismos que controlamos.

• Coste por llamada a herramienta es un proceso node de corta duración: ~45 ms trabajando solo, ~83 ms cuando un gate realmente tiene que razonar (medido en un repositorio de 200 archivos). El arranque de Node domina — tomar una instantánea después de una lectura añade alrededor de 1 ms.

• Nada que mantener. gc se ejecuta al inicio de cada sesión y elimina las reclamaciones, instantáneas y fusiones pendientes de sesiones que ya no existen, por lo que nada se acumula en .git/.

Limitaciones

Dicho claramente, porque una salvaguardia en la que confías erróneamente es peor que no tener ninguna.

• git commit --no-verify se salta la capa de hooks de git. La capa de Claude Code aún lo detecta.

• Los agentes sin hooks ni MCP son invisibles mientras escriben; se detectan en el momento del commit.

• El análisis de comandos deliberadamente no es un analizador de shell completo. Para eval / sh -c / backticks que toquen git, agentclaim se niega solo mientras otra sesión está activa.

• La coexistencia de regiones necesita saber qué vio tu sesión por última vez, por lo que solo se aplica a los archivos que el agente ha leído o escrito a través de sus herramientas. Un archivo modificado por cualquier otra vía (un sed de shell, un editor externo) es invisible para ese razonamiento.

• agentclaim no entiende el significado. Dos ediciones pueden ser textualmente independientes y aun así ser semánticamente incoherentes entre sí; te dice que el otro agente estuvo allí, pero el juicio es tuyo.

• Una fusión triple limpia puede seguir siendo semánticamente incorrecta, exactamente igual que para los humanos. agentclaim te dice que el archivo se fusionó para que lo vuelvas a leer antes de confiar en él.

• Las reclamaciones son por máquina. Nada se sincroniza entre hosts.

Pruebas

npm test

32 comprobaciones de extremo a extremo. La suite reproduce los tres incidentes reales anteriores, demuestra que la herramienta es un no-op completo para una sesión en solitario, y comprueba cada gate con un ejemplo que pasa y otro que falla — un gate que no detecta su propio error es peor que ningún gate, porque infunde confianza.

Enlaces

• Código fuente e incidencias: https://github.com/volkangunay/agentclaim

• npm: https://www.npmjs.com/package/agentclaim

Licencia

MIT © Volkan Günay