agentclaim

Mehrere Agents. Ein Arbeitsbaum. Git wird dich nicht retten.

Dateibesitz für parallele KI-Coding-Agents – damit sie sich nicht mehr stillschweigend überschreiben.

npm i -g agentclaim && agentclaim init

Das Problem

Du betreibst zwei, drei, fünf Coding-Agents gleichzeitig. Sie teilen sich einen Arbeitsbaum.

Git wurde für Menschen gebaut, die auf getrennten Klonen arbeiten und später mergen. Es hat keine Ahnung, was es mit zwei Schreibern anfangen soll, die im selben Moment dasselbe Checkout bearbeiten. Es gibt keine Konfliktmarkierung, keine Warnung, keinen Merge – der zweite Schreibvorgang gewinnt einfach und der erste ist weg.

Das sind drei reale Vorfälle von einem Nachmittag in einem Repo. Alle drei gingen in Produktion. Keiner von ihnen erzeugte eine einzige Fehlermeldung.

1. Das Staging-Rennen

git add erstellt einen Schnappschuss einer Datei so, wie sie in diesem Augenblick ist.

 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

Der Commit lieferte eine neue Money.jsx zusammen mit der alten i18n.js aus. Der Bildschirm zeigte in Produktion rohe Übersetzungsschlüssel. Git meldete Erfolg. Der Folge-Fix-Commit fiel in genau dasselbe Rennen.

2. Das zerstörerische Zurücksetzen

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

Die Arbeit von Sitzung B wurde von der Festplatte zurückgesetzt und dann wegcommittet. Still.

3. Das Tor, das log

Das Deploy-Skript hatte eine Dirty-Tree-Sperre. Es prüfte den Baum zum Deploy-Zeitpunkt, nicht das Rennen zum Commit-Zeitpunkt. Das Tor wurde grün, der Commit war falsch, und das Deploy veröffentlichte treu den falschen Commit.

Related MCP server: asynkor

Die Lösung

Schreibvorgänge werden intelligenter. Commits bleiben streng.

Jeden zweiten Schreiber zu blockieren wäre ein Stoppschild, keine Lösung – und ein Werkzeug, das Arbeit blockiert, die Leute erledigen müssen, wird abgeschaltet. Zwei Agents in einer Datei stehen nur dann in echtem Konflikt, wenn sie dieselbe Region berühren.

Also fragt agentclaim nicht: „Wem gehört diese Datei?" Es fragt: „Was hat sich geändert, seit ich sie zuletzt angesehen habe?" – die einzige Frage, die die Bearbeitungen des anderen Agents von deinen eigenen trennt. Verschiedene Regionen, beide Agents arbeiten. Gleiche Zeilen, einer von ihnen stoppt.

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.

Ein Ganzdatei-Write ist auch kein Konflikt – er wird mit der Arbeit des anderen Agents per git merge-file dreifach zusammengeführt, sodass beide Bearbeitungen landen:

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.

Überlappende Zeilen sind trotzdem kein Stoppschild

Eine gezielte Bearbeitung ist chirurgisch: Sie wird nur angewendet, wenn ihr Ankertext in der Datei, so wie sie gerade steht, noch existiert. Diese eine Eigenschaft leistet die ganze Arbeit.

• Anker noch da → Das Ersetzen behält die Bearbeitungen des anderen Agents, weil deren Änderungen per Definition woanders im Text liegen.

• Anker weg → Das Werkzeug lehnt von selbst ab und der Agent liest erneut.

In beiden Fällen ist das Ergebnis bereits korrekt, also würde Blockieren eine Runde kosten und nichts bringen. agentclaim fügt stattdessen Kontext hinzu:

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.

Was einen Agent tatsächlich stoppt

Vier Dinge, und nur diese:

Nichts im Bearbeitungspfad stoppt. Das ist der Punkt: Ein Werkzeug, das Agents bei normaler Arbeit unterbricht, wird abgeschaltet, und dann schützt es nichts.

Commits sind der strenge Teil

Sobald zwei aktive Sitzungen eine Datei berührt haben, darf keine von beiden sie stagen oder committen – denn genau so liefert ein Agent die halbfertige Arbeit des anderen aus. Vorfall #1 oben.

Dieser Schutz wäre eine Sackgasse, wenn es keinen Ausweg gäbe, also hat er drei:

Sitzungen, die enden oder abstürzen, geben alles frei, was sie hielten, sodass der Baum nie gesperrt bleibt.

Kein Server. Kein Daemon. Keine Abhängigkeiten. Der Speicher ist ein Verzeichnis in .git/.

Schnellstart

npm i -g agentclaim
cd your-repo
agentclaim init

Du willst nicht global installieren? npx agentclaim init funktioniert auch – es kopiert sich zuerst nach ~/.agentclaim/lib, weil Hooks auf einen Pfad zeigen müssen, der morgen noch existiert.

Das war's. init verdrahtet Claude-Code-Hooks und installiert einen Git-pre-commit-Hook (der einen vorhandenen verketten). Überprüfe es jederzeit:

$ 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

Gib deiner Sitzung einen lesbaren Namen, damit die Fehlermeldung des anderen Agents etwas bedeutet:

agentclaim label "money screen"

Was init auf deinem Rechner ändert

Drei Dinge. Sonst nichts.

Keine Netzwerkaufrufe. Keine Telemetrie. Kein Hintergrundprozess. Keine einzige Zeile deines Codes wird berührt, und in git status erscheint nichts Neues.

Es tut nichts, wenn du allein bist

Wenn deine die einzige aktive Sitzung im Baum ist, wird jedes Tor zu „erlauben" kurzgeschlossen. Keine Ansprüche werden durchgesetzt, keine Befehle werden geprüft, nichts zu umgehen.

Das ist beabsichtigt. Ein Tor, das man nicht passieren kann, ist schlimmer als kein Tor, weil man lernt, es zu deaktivieren, und dann schützt es nichts. agentclaim hat nur in der genauen Situation Zähne, für die es existiert.

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

Die vier Tore

Tor 3 ist das, das sonst nichts abfängt. Es liest jeden Pfad im Commit mit git show <sha>:<path> erneut und vergleicht ihn Byte für Byte mit der Datei auf der Festplatte:

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

Es meldet nur Dateien, die von einer anderen Sitzung gehalten werden, sodass normales partielles Staging (git add x, x weiter bearbeiten, committen) nie einen Fehlalarm auslöst.

Funktioniert mit jedem Agent

Drei Integrationsebenen, stärkste zuerst. Verwende so viele, wie zutreffen.

Claude Code – Hooks (am stärksten)

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

Tore laufen vor dem Schreibvorgang oder dem Befehl. Der Agent erhält die Ablehnung als Feedback und wählt von selbst eine andere Datei.

Cursor · Windsurf · Codex · Zed · Cline · alles mit MCP

agentclaim liefert einen MCP-Server mit, sodass jeder Agent, der MCP spricht, am selben Besitzprotokoll teilnehmen kann:

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

Verfügbare Tools: agentclaim_status, agentclaim_claim, agentclaim_release, agentclaim_check, agentclaim_verify_commit. Die Beschreibungen sagen dem Modell, wann es sie aufrufen soll.

Alles andere – der Git-Hook

agentclaim init installiert einen pre-commit-Hook, sodass aider, ein einfaches git commit, deine IDE oder ein Shell-Skript alle dieselbe Prüfung treffen. Nichts zu konfigurieren.

Für Deploy-Skripte und CI verwende das Exit-Code-Tor:

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

Befehle

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

Konfiguration

Optionale .agentclaim.json im Repo-Root:

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

• ttlMinutes – eine Sitzung ohne Aktivität für diese Dauer gilt als verschwunden und ihre Ansprüche können übernommen werden. Jeder Hook-Aufruf aktualisiert den Heartbeat, sodass eine aktive Sitzung nie abläuft.

• touchTtlMinutes – wie lange eine Sitzung andere daran hindert, eine Datei zu committen, nachdem sie sie zuletzt bearbeitet hat. Absichtlich kürzer als ttlMinutes: Noch am Leben zu sein ist nicht dasselbe wie noch in dieser Datei zu arbeiten, und beides zu vermischen ist das, was Schutz in eine Sackgasse verwandelt.

• mode – block (Standard), warn (melden, aber erlauben), off.

• ignore – nie beansprucht. Behalte generierte Dateien hier; wenn Lockfiles und Build-Ausgaben beansprucht werden, feuert das Tor ständig und Leute fangen an, es zu umgehen.

So funktioniert es

.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

• Speicherort ist git rev-parse --git-common-dir, sodass jeder Worktree des Repos ein gemeinsames Registry teilt.

• Claim-Schlüssel umfassen die Worktree-Wurzel, weil derselbe relative Pfad in zwei Worktrees zwei verschiedenen Dateien auf der Platte entspricht. Getrennte Worktrees blockieren einander nie — Worktrees sind eine legitime Lösung für dieses Problem, nicht etwas, das bestraft werden sollte.

• Atomarität ist open(..., 'wx') — O_EXCL. Zwei gleichzeitige Claims, ein Gewinner, kein Race.

• Lebendigkeit ist TTL-basiert. Hooks feuern bei jedem Tool-Aufruf, sodass seen innerhalb von Sekunden frisch bleibt; die Claims eines abgestürzten Agenten sind wieder beanspruchbar und verklemmen das Repo nie.

• Regionsabgleich vergleicht den Snapshot deiner Sitzung mit der Datei auf der Platte mithilfe von git diff --no-index -U0 und führt mit git merge-file zusammen. Alles ist die eigene Semantik von git — diejenige, der du bereits vertraust — ohne zusätzliche Abhängigkeit.

• Merges werden von uns angewendet, nicht injiziert. Das Hook-Ausgabeschema hat ein updatedInput-Feld, aber nichts Überprüfbares besagt, dass es angewendet wird, ohne den Aufruf auch automatisch zu genehmigen, und eine falsche Annahme dort würde die Arbeit des anderen Agenten stillschweigend verwerfen. Deshalb wird der Merge im Stash abgelegt und direkt nach dem Tool-Lauf geschrieben, wobei nur Mechanismen verwendet werden, die wir kontrollieren.

• Kosten pro Tool-Aufruf sind ein kurzlebiger Node-Prozess: ~45 ms bei alleiniger Arbeit, ~83 ms, wenn ein Gate tatsächlich nachdenken muss (gemessen in einem Repo mit 200 Dateien). Der Start von Node dominiert — das Erstellen eines Snapshots nach einem Lesevorgang fügt etwa 1 ms hinzu.

• Nichts zu warten. gc läuft bei jedem Sitzungsstart und entfernt die Claims, Snapshots und ausstehenden Merges von Sitzungen, die nicht mehr existieren, sodass sich in .git/ nichts ansammelt.

Einschränkungen

Klar gesagt, denn ein Schutzmechanismus, dem du zu Unrecht vertraust, ist schlimmer als keiner.

• git commit --no-verify überspringt die git-Hook-Ebene. Die Ebene von Claude Code fängt es trotzdem ab.

• Agenten ohne Hooks oder MCP sind beim Schreiben unsichtbar; sie werden beim Commit abgefangen.

• Die Befehlsanalyse ist bewusst kein vollständiger Shell-Parser. Bei eval / sh -c / Backticks, die git berühren, verweigert agentclaim nur solange eine andere Sitzung aktiv ist.

• Regionskoexistenz muss wissen, was deine Sitzung zuletzt gesehen hat, und gilt daher nur für Dateien, die der Agent über seine Tools gelesen oder geschrieben hat. Eine Datei, die auf anderem Wege geändert wurde (ein Shell-sed, ein externer Editor), ist für diese Argumentation unsichtbar.

• agentclaim versteht keine Bedeutung. Zwei Änderungen können textuell unabhängig sein und dennoch semantisch inkohärent zusammenwirken; es sagt dir, dass der andere Agent da war, aber das Urteil liegt bei dir.

• Ein sauberer Drei-Wege-Merge kann trotzdem semantisch falsch sein, genau wie für Menschen. agentclaim teilt dir mit, dass die Datei gemergt wurde, damit du sie erneut liest, bevor du dich darauf verlässt.

• Claims gelten pro Maschine. Nichts wird über Hosts hinweg synchronisiert.

Tests

npm test

32 End-to-End-Prüfungen. Die Suite spielt alle drei oben genannten realen Vorfälle erneut ab, beweist, dass das Tool für eine einzelne Sitzung ein vollständiger No-op ist, und prüft jedes Gate mit einem bestandenen und einem fehlgeschlagenen Beispiel — ein Gate, das seinen eigenen Fehler nicht erkennt, ist schlimmer als kein Gate, weil es Vertrauen erweckt.

Links

• Quellcode & Issues: https://github.com/volkangunay/agentclaim

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

Lizenz

MIT © Volkan Günay