agent-semaphore

Una capa de coordinación para agentes de codificación en paralelo. Los worktrees no eliminan los conflictos de fusión — los postergan al momento de la integración. agent-semaphore cierra la brecha: reclamaciones con intención sobre ámbitos, una advertencia en el momento de la escritura, predicción de conflictos antes de confirmar nada, y una cola de aterrizaje serializada con una puerta de pruebas obligatoria.

Local-first: sin demonio, sin nube, sin cuenta. Un único archivo SQLite en el directorio común de git es todo el punto de encuentro, por lo que cada worktree del repositorio lo ve por construcción. Multi-proveedor por diseño — hooks de Claude Code y MCP, Codex CLI sobre MCP, todos los demás mediante un hook pre-commit de git.

El problema

Los pull requests escritos por agentes entran en conflicto en un 27,7% — frente al 10–20% de los humanos (AgenticFlict, más de 107K PRs de agentes). En pares coactivos la división es 19,8% intra-agente vs 41,7% entre agentes: los agentes no tienen conciencia horizontal entre sí, y cada producto que implementa coordinación solo coordina sus propios agentes. Una resolución mal hecha de un conflicto conlleva hasta ~26x la densidad de errores del código ordinario (EMSE 2020) — la parte costosa no es el conflicto, es la resolución incorrecta y silenciosa.

El aislamiento está resuelto y mercantilizado (un worktree o un contenedor por agente — todos lo implementan). La predicción y la integración no lo están: nadie ejecuta git merge-tree entre worktrees activos, y las colas de fusión locales independientes prácticamente no existen.

Qué hace

Existen garantías estrictas en exactamente un lugar: la ruta de aterrizaje. Los hooks y pre-commit son control de admisión cooperativo y telemetría, no un límite de seguridad — ASEM_HOOK_OFF=1 y ASEM_OVERRIDE=1 son escapes documentados y auditados. Esto se declara desde el principio porque una capa de coordinación que pretende ser un entorno aislado es peor que ninguna.

Inicio rápido

uv tool install git+https://github.com/alwh1te/agent-semaphore     # asem on PATH
# or, from a clone: uv tool install -e .

cd <your repo>
curl -O https://raw.githubusercontent.com/alwh1te/agent-semaphore/main/.agent-semaphore.toml.example
mv .agent-semaphore.toml.example .agent-semaphore.toml   # set the gate command, hot classes, target branch
asem init                                   # state in .git/agent-semaphore/
asem install --git-hooks                    # Claude Code hooks + .mcp.json + git pre-commit
asem doctor                                 # PASS checklist

asem claim src/api/ -i "refactor auth parsing" --ttl 30m   # exit 3 = held by someone else
asem check src/api/routes.py                               # who holds it, and what for
asem radar                                                 # conflicts between worktrees, before any commit
asem land feature-branch                                   # rebase -> gate -> CAS into the staging branch
asem notices                                               # messages addressed to you
asem status | asem queue status | asem doctor

Los códigos de salida son parte del contrato: 0 ok/libre, 3 retenido/conflicto/rebotado, 2 uso, 1 error interno — un script puede distinguir "la coordinación dijo que no" de "la herramienta se rompió".

Medido

Nadie en este espacio había medido si las reclamaciones realmente reducen los conflictos, por lo que el repositorio incluye dos puntos de referencia propios.

Con script (docs/benchmark.md, 60 ejecuciones, agentes deterministas, cumplimiento = 1 por construcción): conflictos de integración 60% → 0%, intervenciones humanas 9 → 0.

Agentes en vivo (docs/bench-llm.md, 40 ejecuciones de dos agentes claude -p concurrentes, $17,95):

Tres hallazgos que el arnés con script no pudo producir estructuralmente:

1. Los conflictos se eliminan con la puesta al día, no con la reclamación. 10 de cada 10 ejecuciones donde un agente reorganizó su base sobre la rama de su par se fusionaron limpiamente; cada ejecución coordinada con conflicto es una donde ambos agentes reclamaron cortésmente y ninguno reorganizó. Una reclamación serializa la escritura — no te entrega el resultado del otro agente. Ese hallazgo es lo que produjo la característica "la liberación despierta a los que esperan y nombra la rama".

2. El hook nunca se activó una vez en 40 ejecuciones. Con el protocolo en el prompt, los agentes reclaman antes de editar y nunca escriben en un ámbito retenido, por lo que la aplicación resultó ser un seguro que no fue necesario — no la capa de trabajo.

3. La coordinación puede convertir un conflicto en trabajo que nunca ocurrió. En dos ejecuciones, el agente bloqueado citó al titular, su intención y su rama, y abandonó su tarea. Sin la columna did_work junto a ICR, esas ejecuciones se leen como un éxito limpio — razón por la cual la columna está ahí.

La deriva semántica (textualmente limpia, semánticamente rota) sobrevive a todas las capas de asesoría en ambos puntos de referencia y es detectada solo por la puerta obligatoria de la cola.

Cómo se conecta

• Claude Code — asem install escribe el proyecto .claude/settings.json (PreToolUse + PostToolUse), añade Bash(asem:*) y mcp__semaphore__* a la lista de permitidos, y registra el servidor MCP en .mcp.json. El cableado confirmado es portátil entre máquinas ($HOME y un asem desnudo), por lo que un repositorio compartido entre máquinas no lleva las rutas de un host.

• MCP (asem mcp, clave de servidor semaphore) — claim, release, check, status, extend, report_intent, radar, enqueue_land, land_status. Cada respuesta drena las notificaciones pendientes, por lo que los agentes se enteran de robos, rebotes y objetivos movidos sin necesidad de sondeo.

• Codex CLI — el mismo servidor MCP a través de ~/.codex/config.toml, más un fragmento de protocolo para AGENTS.md. Codex sin cabeza cancela silenciosamente las llamadas MCP a menos que las herramientas estén preaprobadas; docs/integration.md tiene la configuración funcional.

• Cualquier otra cosa — asem install --git-hooks coloca una puerta pre-commit en el directorio de hooks compartido (carga en cadena cualquier hook que estuviera allí antes).

Documentación

• docs/00-research.md — el dossier de investigación sobre el que se basa este diseño: el problema medido, el panorama de herramientas, los trabajos previos clásicos que vale la pena tomar prestados, los artículos de 2024–26 y las tres brechas confirmadas en el mercado.

• docs/adr/ADR-001-architecture.md — la arquitectura, más un registro de riesgos y diez ataques adversariales de una revisión ciega (ocho de ellos cambiaron el diseño).

• docs/adr/ADR-002-stack-and-state.md — pila, nomenclatura y dónde reside el estado.

• docs/benchmark.md / docs/bench-llm.md — ambos puntos de referencia: método, resultados y las limitaciones detalladas.

• docs/integration.md — instalación y qué está cableado dónde.

Estado

v1 está implementada y en uso interno: el repositorio coordina sus propios agentes a través de ella. 150 pruebas, una puerta de latencia de hook p95 en CI, ambos puntos de referencia reproducibles desde el repositorio.

Límites conocidos, declarados claramente: la promoción de la rama de preparación a main sigue siendo manual y sin puerta (asem promote es la siguiente característica); la cola nunca empuja; no hay alcance a nivel de símbolo, ni detección de conflictos semánticos más allá de la puerta de pruebas, ni autorresolución con LLM (el techo publicado es de ~55–60% de corrección, que no es suficientemente bueno para ejecutarse sin supervisión); y multi-host es un diseño de v2, aunque el esquema ya lleva la columna host.

Desarrollo

uv run pytest -q                          # 150 tests
uv run ruff check . && uv run ruff format --check .
uv run python bench/hook_latency.py 200   # hook latency gate (p95 < 100 ms)
uv run python bench/runner.py --seeds 3 && uv run python bench/report.py

El script del hook PreToolUse se distribuye fuera del paquete y debe permanecer solo con la biblioteca estándar — se ejecuta en cada escritura de cada agente, por lo que tiene un presupuesto de latencia en lugar de dependencias. Consulte CONTRIBUTING.md.

Licencia

MIT — consulte LICENSE.