agent-semaphore

Eine Koordinationsschicht für parallele Codierungs-Agenten. Worktrees beseitigen Merge-Konflikte nicht – sie verschieben sie auf den Integrationszeitpunkt. agent-semaphore schließt die Lücke: absichtstragende Beanspruchungen (claims) von Bereichen, eine Warnung im Moment des Schreibens, Konfliktvorhersage bevor etwas committet wird und eine serialisierte Landing-Queue mit einem obligatorischen Test-Gate.

Local-first: kein Daemon, keine Cloud, kein Konto. Eine einzelne SQLite-Datei im git-common-Verzeichnis ist der gesamte Treffpunkt, sodass jeder Worktree des Repos sie konstruktionsbedingt sieht. Von Haus aus herstellerübergreifend — Claude Code Hooks und MCP, Codex CLI über MCP, alle anderen über einen git pre-commit Hook.

Das Problem

Von Agenten geschriebene Pull-Requests haben eine Konfliktrate von 27,7 % – im Vergleich zu 10–20 % bei menschlichen (AgenticFlict, 107K+ Agenten-PRs). Bei ko-aktiven Paaren beträgt die Aufteilung 19,8 % Intra-Agent vs. 41,7 % Cross-Agent: Agenten haben keine horizontale Wahrnehmung voneinander, und jedes Produkt, das Koordination ausliefert, koordiniert nur seine eigenen Agenten. Ein schlecht gelöster Konflikt weist eine bis zu ~26x höhere Fehlerdichte auf als normaler Code (EMSE 2020) – der teure Teil ist nicht der Konflikt, sondern die stille, schlechte Lösung.

Isolation ist gelöst und standardisiert (ein Worktree oder Container pro Agent – jeder liefert es aus). Vorhersage und Integration nicht: niemand führt git merge-tree zwischen aktiven Worktrees aus, und eigenständige lokale Merge-Queues existieren praktisch nicht.

Was es tut

Harte Garantien existieren an genau einer Stelle: dem Landing-Pfad. Hooks und pre-commit sind kooperative Zugangskontrolle und Telemetrie, keine Sicherheitsgrenze — ASEM_HOOK_OFF=1 und ASEM_OVERRIDE=1 sind dokumentierte, geprüfte Notausgänge. Dies wird vorab gesagt, weil eine Koordinationsschicht, die vorgibt, eine Sandbox zu sein, schlimmer ist als keine.

Schnellstart

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

Exit-Codes sind Teil des Vertrags: 0 ok/frei, 3 gehalten/Konflikt/zurückgeworfen, 2 Nutzung, 1 interner Fehler — ein Skript kann "Koordination sagt nein" von "das Werkzeug ist kaputt" unterscheiden.

Gemessen

Niemand in diesem Bereich hatte gemessen, ob Beanspruchungen tatsächlich Konflikte reduzieren, daher liefert das Repo zwei eigene Benchmarks.

Skriptbasiert (docs/benchmark.md, 60 Läufe, deterministische Agenten, Compliance = 1 konstruktionsbedingt): Integrationskonflikte 60 % → 0 %, menschliche Eingriffe 9 → 0.

Live-Agenten (docs/bench-llm.md, 40 Läufe von zwei gleichzeitigen claude -p Agenten, $17,95):

Drei Erkenntnisse, die das skriptbasierte Testgerüst strukturell nicht produzieren konnte:

1. Konflikte werden durch das Catch-up beseitigt, nicht durch die Beanspruchung. 10 von 10 Läufen, in denen ein Agent auf den Branch seines Peers rebasierte, fusionierten sauber; jeder konfliktreiche koordinierte Lauf ist einer, in dem beide Agenten höflich beanspruchten und keiner rebasierte. Eine Beanspruchung serialisiert Schreiben — sie gibt dir nicht das Ergebnis des anderen Agenten. Diese Erkenntnis führte zur Funktion "Freigabe weckt die Wartenden und nennt den Branch".

2. Der Hook wurde in 40 Läufen kein einziges Mal ausgelöst. Mit dem Protokoll im Prompt beanspruchen Agenten vor dem Bearbeiten und schreiben nie in einen gehaltenen Scope, sodass sich die Durchsetzung als nicht benötigte Versicherung herausstellte — nicht als die arbeitende Schicht.

3. Koordination kann einen Konflikt in Arbeit verwandeln, die nie stattfand. In zwei Läufen zitierte der blockierte Agent den Halter, seine Absicht und seinen Branch und gab seine Aufgabe auf. Ohne die did_work-Spalte neben ICR lesen sich diese Läufe als sauberer Erfolg — weshalb die Spalte da ist.

Semantische Drift (textuell sauber, semantisch kaputt) überlebt jede beratende Schicht in beiden Benchmarks und wird nur durch das obligatorische Gate der Warteschlange abgefangen.

Wie es eingebunden wird

• Claude Code — asem install schreibt .claude/settings.json des Projekts (PreToolUse + PostToolUse), fügt Bash(asem:*) und mcp__semaphore__* zur Allow-Liste hinzu und registriert den MCP-Server in .mcp.json. Committete Verkabelung ist host-portabel ($HOME und ein nacktes asem), sodass ein über Maschinen geteiltes Repo nicht die Pfade eines Hosts trägt.

• MCP (asem mcp, server key semaphore) — claim, release, check, status, extend, report_intent, radar, enqueue_land, land_status. Jede Antwort leert ausstehende Benachrichtigungen, sodass Agenten ohne Polling von Diebstählen, Zurückweisungen und verschobenen Zielen erfahren.

• Codex CLI — derselbe MCP-Server via ~/.codex/config.toml, plus ein Protokollschnipsel für AGENTS.md. Headless Codex bricht MCP-Aufrufe stillschweigend ab, es sei denn, die Tools sind vorab genehmigt; docs/integration.md enthält die funktionierende Konfiguration.

• Alles andere — asem install --git-hooks platziert ein pre-commit-Gate im gemeinsamen Hooks-Verzeichnis (es lädt jeden vorher vorhandenen Hook nach).

Dokumentation

• docs/00-research.md — das Forschungsdossier, auf dem dieses Design aufbaut: das gemessene Problem, die Werkzeuglandschaft, die klassische, nachahmenswerte Vorarbeit, die Papiere von 2024–26 und die drei bestätigten Marktlücken.

• docs/adr/ADR-001-architecture.md — die Architektur, plus ein Risikoregister und zehn adversarial Angriffe aus einer Blindbegutachtung (acht davon änderten das Design).

• docs/adr/ADR-002-stack-and-state.md — Stack, Benennung und wo der Zustand lebt.

• docs/benchmark.md / docs/bench-llm.md — beide Benchmarks: Methode, Ergebnisse und die explizit genannten Einschränkungen.

• docs/integration.md — Installation und was wo verdrahtet ist.

Status

v1 ist implementiert und dogfooded: das Repository koordiniert seine eigenen Agenten darüber. 150 Tests, ein p95 Hook-Latenz-Gate in CI, beide Benchmarks aus dem Repo reproduzierbar.

Bekannte Grenzen, klar ausgesprochen: Promotion vom Staging-Branch zu main ist noch manuell und ungated (asem promote ist das nächste Feature); die Warteschlange pusht nie; es gibt kein Symbol-Level-Scoping, keine semantische Konflikterkennung jenseits des Test-Gates, keine LLM-Autoauflösung (die veröffentlichte Obergrenze liegt bei ~55–60 % Korrektheit, was nicht gut genug ist, um unbeaufsichtigt zu laufen); und Multi-Host ist ein v2-Design, obwohl das Schema bereits die host-Spalte trägt.

Entwicklung

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

Das PreToolUse Hook-Skript wird außerhalb des Pakets mitgeliefert und muss stdlib-only bleiben — es wird bei jedem Schreibvorgang jedes Agenten ausgeführt, hat also ein Latenzbudget statt Abhängigkeiten. Siehe CONTRIBUTING.md.

Lizenz

MIT — siehe LICENSE.