Worktrees für Coding-Agents verwalten

Worktrees lassen sich leicht anlegen und genauso leicht vergessen. Man erstellt einen, damit ein Agent isoliert an einem Branch arbeiten kann, der Agent wird fertig, man prüft den Diff – und dann liegt das Verzeichnis einfach da. Eine Woche später scrollt git worktree list über den Bildschirm hinaus, du -sh im Repo zeigt zwölf Gigabyte, und drei dieser Verzeichnisse verweisen auf Branches, die schon vor Tagen gemergt und gelöscht wurden. Niemand hat sich bewusst dafür entschieden, sie zu behalten. Sie haben sich angesammelt, weil das Anlegen ein Befehl war und das Aufräumen eine lästige Pflicht.

Das ist der Teil der parallelen Agentenarbeit, vor dem einen niemand warnt. Das Isolationsprimitiv ist gut dokumentiert; unser Leitfaden zu Git-Worktrees für KI-Coding-Agents behandelt die Mechanik von Anlegen und Branchen ausführlich. Der Lebenszyklus nach dem „Fertig“ ist der Punkt, an dem der Schmerz sitzt, und er verschlimmert sich schnell, wenn das, was die Worktrees erzeugt, ein Agent ist, der fünf pro Minute öffnen kann und keinerlei Instinkt zum Aufräumen hat. Dieser Artikel dreht sich um genau diese zweite Hälfte: die Aufräumdisziplin, die konkreten Befehle, den Fehlermodus, der bei jedem Schritt lauert, und den Punkt, an dem ein selbst geschriebenes Skript nicht mehr ausreicht.

Sharkly ist eine Antwort auf das Problem „Wer räumt auf“: Es führt jede Task in ihrem eigenen Worktree aus und behandelt diesen Worktree als Teil des Lebenszyklus der Task – statt als Verzeichnis, an das man sich erinnern muss. Dazu kommen wir noch. Zuerst die Mechanik, denn man sollte die manuelle Variante verstanden haben, bevor man sich entscheidet, sie nicht mehr per Hand zu erledigen.

TL;DR

Ein Git-Worktree ist ein zweites Arbeitsverzeichnis, das mit einem Repository verknüpft ist und über einen eigenen Branch, Index und HEAD verfügt. Agenten lassen sie sich anhäufen, weil jeder Lauf Isolation will und keiner von ihnen hinter sich aufräumt. Die Aufräum-Leitplanke besteht aus vier Befehlen: git worktree list, um zu sehen, was existiert, git worktree remove, um einen fertigen Worktree zu löschen, git worktree prune, um veraltete Metadaten zu bereinigen, und git worktree lock, um einen zu schützen, den man behalten möchte. Jeder davon hat einen Fehlermodus, der verwaiste Verzeichnisse, verlorene Arbeit oder blockierte Branches hinterlässt, wenn man einen Schritt auslässt. Die manuelle Variante funktioniert für eine Handvoll Worktrees. Darüber hinaus sollte man jeden Worktree an einen Task-Datensatz binden, damit das Aufräumen einen Verantwortlichen hat – genau das macht Sharkly automatisch.

Warum sich Worktrees mit Agenten schneller anhäufen

Ein Worktree hat einen Lebenszyklus, den ein Mensch ganz natürlich verwaltet: Man legt ihn an, arbeitet darin, merged und löscht ihn. Der Löschschritt setzt voraus, dass ein Mensch daran denkt. Agenten untergraben diese Annahme gleich in zwei Richtungen.

Erstens, die Menge. Ein Entwickler, der vier Agenten parallel laufen lässt, legt vier Worktrees pro Stunde an, nicht einen pro Tag. Unser Beitrag zum parallelen Ausführen mehrerer Claude-Code-Agenten erklärt, warum diese Zahl so schnell steigt. Zweitens, kein Aufräum-Instinkt. Ein Agent liest die Aufgabe, erledigt die Arbeit, schreibt das Ergebnis und hört auf. Er denkt nicht: „Der Branch ist gemergt, dieses Verzeichnis ist jetzt nur noch Ballast.“ So überleben die Verzeichnisse ihren eigenen Nutzen, und die Überlebenden sind das Problem: veraltete Checkouts auf gelöschten Branches, halbfertige Experimente, die der Agent aufgegeben hat, und doppelte node_modules-Bäume, die in jedem davon Speicherplatz fressen.

Die Kosten sind nicht abstrakt. Jeder Worktree ist ein vollständiger Checkout plus alles, was der Agent darin installiert hat. Zehn Worktrees in einem mittelgroßen JavaScript-Repo sind zehn node_modules-Verzeichnisse. Die Festplatte füllt sich, git status wird über das gesamte Set hinweg langsamer, und die nächste Person, die git worktree list ausführt, kann nicht mehr sagen, welche Verzeichnisse aktive Arbeit sind und welche nur Überreste.

Die Aufräum-Leitplanke, Schritt für Schritt

Hier ist der gesamte Lebenszyklus in vier Befehlen. In dieser Reihenfolge ausgeführt, bleiben die Fehlermodi geschlossen.

Verschaff dir einen Überblick. Jeder Aufräumdurchgang beginnt hier:

git worktree list
# /repo              a1b2c3d [main]
# /repo-auth-refactor 4d5e6f7 [auth-refactor]
# /repo-fix-logging   8g9h0i1 [fix-logging]

Der Fehlermodus, wenn du das überspringst: Du löschst das falsche Verzeichnis. Zwei Agenten auf ähnlich benannten Branches erzeugen ähnlich benannte Worktree-Pfade, und wenn du den aktiven löschst, kostet dich das nicht committete Arbeit. Lies die Liste, bevor du irgendetwas anfasst.

Entferne einen fertigen Worktree. Sobald der Branch eines Worktrees gemergt ist und du bestätigt hast, dass nichts Unfertiges darin liegt:

git worktree remove /repo-fix-logging

Der Fehlermodus: remove verweigert den Dienst, wenn der Worktree nicht committete Änderungen oder nicht verfolgte Dateien enthält – das ist die sichere Standardeinstellung. Der unsichere Weg ist, zu --force zu greifen, nur um die Fehlermeldung loszuwerden. --force auf einem unsauberen Worktree löscht echte Arbeit, die ein Agent erzeugt, aber nie committet hat. Wenn remove sich beschwert, sieh dir zuerst das Verzeichnis an; die Beschwerde hat meistens recht.

Bereinige die veralteten Metadaten. Wenn ein Worktree-Verzeichnis mit rm -rf statt mit git worktree remove gelöscht wurde, hält Git weiterhin einen administrativen Eintrag darüber. Das ist der klassische verwaiste Eintrag:

git worktree prune
git worktree prune --dry-run   # preview first

Der Fehlermodus: Wenn du prune überspringst, bleiben Geistereinträge in git worktree list zurück, und schlimmer noch: Git weigert sich möglicherweise, einen Branch wiederzuverwenden, von dem es glaubt, er sei noch irgendwo ausgecheckt. prune räumt die Buchhaltung auf. Führe zuerst --dry-run aus, damit du siehst, was es verwerfen wird, bevor es das tut. Die Git-Worktree-Dokumentation erklärt genau, was prune als veraltet betrachtet.

Sperre die Worktrees, die du behalten willst. Ein Worktree auf einer langsamen externen Festplatte oder einer mit einem lang laufenden Experiment sollte nicht von einem aggressiven Aufräumskript bereinigt werden:

git worktree lock /repo-experiment --reason "release repro, keep until 2.0 ships"

Der Fehlermodus: Ohne Sperre kann ein nächtlicher Aufräumjob, der alles „Veraltete“ bereinigt, einen Worktree entfernen, den du bewusst geparkt hast. Die Sperre plus eine Begründung ist der Unterschied zwischen einem Aufräumskript, dem du vertraust, und einem, das du abschaltest, nachdem es etwas Wichtiges gefressen hat.

Wo das Aufräumskript nicht mehr skaliert

Du kannst alle vier Schritte automatisieren. Ein Cron-Job, der Worktrees auflistet, jeden Branch gegen die gemergte Historie prüft und die gemergten entfernt, sind dreißig Zeilen Shell. Das funktioniert, und für einen Solo-Entwickler mit ein paar Agenten reicht es aus. Setz das Skript ein, wenn die Anzahl der Worktrees klein ist und eine Person das Repository verantwortet.

Es stößt beim Urteilsvermögen an seine Grenzen, nicht beim Durchsatz. Ein Skript kann erkennen, dass ein Branch gemergt wurde. Es kann nicht erkennen, dass ein Worktree die nicht committete Arbeit eines Agenten enthält, die du noch nicht geprüft hast, oder dass ein „veralteter“ Branch eigentlich eine pausierte Aufgabe ist, die jemand fortsetzen will. Sobald das Aufräumen erfordert, die Absicht hinter einem Worktree zu kennen, wird eine Regel, die nur den Git-Status sieht, irgendwann etwas löschen, das wichtig war. Die andere Obergrenze ist die Koordination: Auf einer geteilten Maschine weiß das Aufräumskript einer Person nicht, was die Agenten einer anderen gerade tun, und die Frage „Kann das gefahrlos entfernt werden“ lässt sich nicht mehr allein anhand von git worktree list beantworten. Mehr zu diesem Problem mit geteilten Maschinen findest du in unserer Übersicht zu Tools für die Verwaltung paralleler KI-Coding-Agents.

Was ein Task-Board bringt

Die Lösung besteht darin, jedem Worktree einen Verantwortlichen zu geben, der länger lebt als die Shell-Sitzung. Binde jeden Worktree an einen Task-Datensatz, und das Aufräumen ist nicht mehr die Frage „Welche Verzeichnisse sehen veraltet aus“, sondern „Welche Tasks sind erledigt und geprüft“.

Auf dieser Ebene setzt Sharkly an. Du hast bereits Coding-Agents; Sharkly macht daraus ein Team, indem jeder Lauf zu einer Task wird. Wenn eine Task startet, bereitet der lokale Dienst auf dem verbundenen Computer einen isolierten Worktree dafür vor. Wenn das Ergebnis der Task zur Prüfung zurückkommt und eine Person es annimmt, endet der Lebenszyklus des Worktrees mit der Task, statt als Verzeichnis weiterzubestehen, an das sich niemand erinnert. Die Aufräumfrage hat eine Antwort, weil der Worktree nie anonym war.

Die Arbeitsteilung bleibt ehrlich. Agenten beanspruchen Tasks, arbeiten in isolierten Worktrees, führen Tests aus und liefern den Diff zurück. Menschen geben die Richtung vor und entscheiden über den Merge- und Release-Schritt. Sharkly ist kein Ersatz für Claude Code, Codex oder die oben genannten Git-Befehle; es ergänzt den gemeinsamen Datensatz, damit Isolation, Fortschritt, Ergebnisse und Aufräumen von der Anfrage bis zum Release sichtbar bleiben, statt sich über verschiedene Terminals zu verteilen. Wenn du einen Agenten laufen lässt und das manuelle Aufräumen zehn Sekunden dauert, brauchst du das noch nicht. Wenn die Worktree-Liste über den Bildschirm hinaus scrollt, ist das Verwaltungsproblem das eigentliche Problem, und unser Beitrag dazu, Menschen über Agentenläufe hinweg im Loop zu halten, behandelt die Review-Seite davon.

Die Checkliste, die du heute durchgehen kannst

Geh diesen Durchgang in jedem Repo durch, in dem Agenten gearbeitet haben:

git worktree list ausführen und vollständig lesen, bevor du irgendetwas entfernst.
Für jeden fertigen Worktree: prüfen, ob der Branch gemergt wurde, kontrollieren, dass das Verzeichnis sauber ist, dann git worktree remove (niemals --force auf einem unsauberen Worktree).
git worktree prune --dry-run, durchsehen, dann git worktree prune, um verwaiste Metadaten zu bereinigen.
Jeden Worktree, den du bewusst behalten willst, mit git worktree lock und einer Begründung sperren.
Festplatte prüfen: du -sh über das gesamte Worktree-Set, und doppelte Dependency-Installationen aus toten Bäumen löschen.
Wenn du das öfter als einmal am Tag machst, hör auf, das Aufräumen zu skripten, und gib jedem Worktree stattdessen einen Task-Verantwortlichen.

Du kannst die vier Befehle behalten und sie von Hand ausführen, oder deine bestehenden Coding-Agents über Sharkly laufen lassen, damit der Worktree gemeinsam mit der zugehörigen Task angelegt, verfolgt und stillgelegt wird.