Was ist ein Git-Worktree und wie nutzen Agenten ihn?

Was geht schief, wenn zwei Agenten im selben Verzeichnis arbeiten?

Coding-Agenten laufen bei uns inzwischen meist parallel: Eine Sitzung schreibt ein neues Feature, eine zweite behebt einen Fehler, und Subagenten ändern gleichzeitig verschiedene Dateien. Arbeiten alle im selben Verzeichnis, teilen sie sich dieselben Dateien, denselben Branch und denselben Git-Index. In dem Repository, in dem wir diffox entwickeln, haben wir dafür mehrmals bezahlt. Aus jedem Fall wurde eine Regel:

• Ein einfacher Commit nahm auch die Arbeit eines anderen Agenten mit. git commit committet alles, was im Index liegt, auch Dateien, die ein anderer Agent im selben Verzeichnis vorgemerkt hat. Unsere Regel: Parallel arbeitende Agenten committen nur ihre eigenen Dateien (git commit --only <Pfade>).
• Ein git checkout -b wechselte den Branch einer anderen Sitzung. Die Shell des Agenten springt bei jedem Befehl ins Startverzeichnis zurück, und ein Git-Befehl ohne Pfadangabe hat einmal den Branch einer parallelen Sitzung gewechselt. Unsere Regel: Jeder Git-Befehl nennt den Pfad ausdrücklich (git -C <absoluter Pfad>).
• Eine Sitzung plante Änderungen in einem Verzeichnis, das in 40 Minuten 3-mal den Branch wechselte. Deshalb gibt es den Hook zum Sitzungsstart, den wir im Beitrag über Hooks beschrieben haben.
• Auch unser Aufräumskript machte diesen Fehler. Das Skript, das gemergte Branches aufräumt, schaltete jedes saubere Verzeichnis, das es fand, auf dev um. Ein sauberes Verzeichnis kann aber einer anderen Sitzung gehören, die nur noch nicht zu schreiben begonnen hat; das Skript wechselte den Branch dieser Sitzung. Heute schaltet es nur noch Verzeichnisse um, die auf dev, auf main oder auf einem Branch mit gemergtem Pull Request stehen.

Gemeinsam ist allen Fällen ein einziges Verzeichnis. Genau dafür gibt es Worktrees: Jeder Agent bekommt sein eigenes Verzeichnis, seinen eigenen Branch und seinen eigenen Index. Wie Sie unten sehen, trennt ein Worktree aber nicht alles. Die Einstellung isolation: worktree in Claude Code haben wir im Beitrag über Subagenten beschrieben. Dieser Beitrag schaut auf das Repository, das sich die Agenten teilen.

Was ist ein Git-Worktree?

Laut Git-Dokumentation kann ein Repository mehrere Arbeitsverzeichnisse (working trees) haben, sodass Sie mehrere Branches gleichzeitig ausgecheckt haben können. Das Verzeichnis, das Sie mit git clone bekommen, ist der Haupt-Worktree. Die Worktrees, die Sie mit git worktree add anlegen, heißen verknüpfte Worktrees (linked worktrees).

Ein verknüpfter Worktree teilt mit dem Repository alles bis auf ein paar eigene Dateien wie HEAD und Index. Die Commit-Historie liegt nur einmal vor; jeder Worktree hat nur seine eigene Kopie der Dateien. Den Großteil der Arbeit erledigen diese Befehle:

git worktree add -b suche ../projekt-suche   # neues Verzeichnis, neuer Branch
git worktree list                            # alle Worktrees
git worktree remove ../projekt-suche         # entfernt ihn, wenn er sauber ist
git worktree prune                           # löscht die Einträge von Worktrees, deren Verzeichnis von Hand gelöscht wurde

Einige Fehler verhindert Git von selbst. Ein Branch kann immer nur in einem Worktree ausgecheckt sein: add lehnt standardmäßig einen Branch ab, der schon in einem anderen Worktree ausgecheckt ist. Und remove entfernt nur saubere Worktrees; um einen mit nicht committeten Änderungen oder nicht versionierten Dateien zu löschen, brauchen Sie --force.

Der Unterschied zwischen Worktree und Branch. Ein Branch ist ein Name, der auf einen Commit zeigt. Ein Worktree ist ein Verzeichnis, in dem die Dateien eines Branches ausgecheckt sind. Wechseln Sie in einem einzigen Verzeichnis den Branch, ändern sich die Dateien für alle, die darin arbeiten. Mit Worktrees bleibt jeder Agent in seinem eigenen Verzeichnis, auf seinem eigenen Branch. Ein Hinweis: Die Git-Dokumentation selbst nennt mehrere Checkouts noch experimentell und schreibt, dass die Unterstützung für Submodule unvollständig ist.

Wie öffnet man in Coding-Tools einen Worktree?

Alle fünf Tools können selbst einen Worktree anlegen; in Gemini CLI ist die Funktion experimentell und wird in den Einstellungen eingeschaltet. Unterschiede gibt es darin, wo der Worktree angelegt wird, von welchem Commit er startet, ob er Dateien mitbringt, die Git ignoriert (etwa .env), und wann er gelöscht wird.

Quelle: die Worktree-Dokumentation des jeweiligen Tools, 18. Oktober 2026. „Steht nicht in der Dokumentation“ heißt: Auf der Seite, die wir an diesem Tag gelesen haben, fanden wir dazu keinen Satz. Die Codex-Zeile gilt für Codex in der ChatGPT-Desktop-App, die die Seite beschreibt. Das Aufräumen in Cursor ist für Version 3.5 und neuer beschrieben. Auch die GitHub-Copilot-App öffnet für jede Sitzung einen eigenen Worktree und Branch.

Der wichtigste Unterschied ist der Startpunkt. Claude Code startet standardmäßig beim Standard-Branch des Remote-Repositorys; Commits, die Sie noch nicht gepusht haben, fehlen im neuen Worktree. Copilot CLI startet dagegen beim HEAD des Checkouts, in dem Sie gerade sind. Codex überträgt sogar die nicht committeten Änderungen des gewählten Branches in den neuen Worktree. Wählen Sie diese Einstellung bewusst, je nachdem, was der Agent sehen soll.

Dateien, die Git ignoriert, kommen nicht in den neuen Worktree. Claude Code und Codex lesen dafür eine Datei mit demselben Namen: .worktreeinclude im Wurzelverzeichnis des Repositorys. Sie wird in der Syntax von .gitignore geschrieben und kopiert nur Dateien, die Git ignoriert. In Cursor übernehmen das Setup-Befehle in .cursor/worktrees.json; das Beispiel in der Dokumentation kopiert .env mit cp.

Bei Abhängigkeiten raten zwei Tools Unterschiedliches. Cursor rät davon ab, Abhängigkeiten per Symlink in den Worktree zu holen, weil das im Haupt-Worktree Probleme machen kann. Claude Code dagegen kann mit der Einstellung worktree.symlinkDirectories große Verzeichnisse wie node_modules per Symlink in jeden Worktree holen.

Für paralleles Arbeiten gibt es auch fertige Befehle. Der Skill /batch von Claude Code teilt eine große Änderung auf 5 bis 30 Subagenten auf, die jeweils in ihrem eigenen Worktree arbeiten. Der Befehl /best-of-n von Cursor lässt dieselbe Aufgabe auf mehreren Modellen laufen und gibt jedem Lauf einen eigenen Worktree. Die Agent-Teams (agent teams) von Claude Code dagegen trennen ihre Mitglieder nicht in Worktrees; die Dokumentation empfiehlt, die Arbeit so aufzuteilen, dass jedes Mitglied für andere Dateien zuständig ist.

Google hat Gemini CLI am 18. Juni 2026 für kostenlose Nutzer sowie für Abonnenten von Google AI Pro und Ultra eingestellt und sie auf Antigravity CLI verwiesen; mit einem kostenpflichtigen API-Schlüssel oder einer Firmenlizenz können Sie Gemini CLI weiter nutzen. Die Dokumentation von Antigravity haben wir am 28. Oktober 2026 gelesen. Laut der Seite zu Subagenten kann der Hauptagent einem Subagenten, den er startet, einen eigenen Git-Worktree geben; wird der Subagent beendet, wird dieser Worktree automatisch gelöscht. Von welchem Commit der Worktree startet und ob er Dateien wie .env mitbringt, steht nicht in der Dokumentation. Die Desktop-App kann eine neue Konversation direkt in einem eigenen Worktree öffnen; in der CLI haben wir dafür kein Flag gefunden.

Was trennt ein Worktree und was nicht?

Man stellt sich einen Worktree leicht als vollständige Sandbox vor. Git gibt jedem Worktree aber nur wenige Dinge für sich. Der Rest ist gemeinsam, und um einen Teil davon kümmert sich Git überhaupt nicht:

Einstellungen und Hook-Pfad sind gemeinsam. Laut Git gilt die Konfigurationsdatei des Repositorys standardmäßig für alle Worktrees. In unserem Repository steht in dieser Datei auch, wo die Git-Hooks liegen (core.hooksPath), als ein einziger absoluter Pfad. Deshalb läuft der pre-push-Hook, der vor einem Push ausgeführt wird, aus der Kopie im Haupt-Worktree und nicht aus der Kopie auf dem Branch, den Sie pushen. Am 24. August 2026 haben wir diesem Hook auf einem Worktree-Branch eine neue Regel hinzugefügt, und seine 11 Tests liefen grün durch. Ein Push aus demselben Worktree ging trotzdem durch, weil im Haupt-Worktree noch die alte Fassung lag. Dasselbe gilt für andere Einstellungen wie die Identität (user.email); für Einstellungen pro Worktree müssen Sie in Git extensions.worktreeConfig einschalten.

Auch die Berechtigungen der Tools können gemeinsam sein. In Claude Code wird eine Freigabe mit “Yes, and don’t ask again”, die Sie in einem Worktree erteilen, in die Datei .claude/settings.local.json des Haupt-Worktrees geschrieben und gilt in allen Worktrees. Auch in Copilot CLI teilen verknüpfte Worktrees die Berechtigungen des Haupt-Repositorys.

Branches und Stash sind gemeinsam. Laut Git sind alle Referenzen, die mit refs/ beginnen, zwischen den Worktrees geteilt, und der letzte Stash liegt in refs/stash. Ein git stash pop ohne Angabe eines Stashs nimmt den letzten. Legt man diese Sätze aus der Git-Dokumentation nebeneinander, ergibt sich: Ein git stash pop in einem Worktree nimmt den letzten Stash, auch wenn ihn ein Agent in einem anderen Worktree abgelegt hat. In einem Repository, in dem Agenten parallel arbeiten, ist ein temporärer Commit sicherer als ein Stash.

Was außerhalb von Git liegt, wird gar nicht getrennt. Eine Datenbank, ein Port, ein Cache oder ein ignoriertes Datenverzeichnis wissen nichts von Worktrees. In unserem Repository holen wir ein großes Messverzeichnis (.runs) per Symlink in jeden Worktree, weil dort bezahlte Messergebnisse liegen, die beim Löschen eines Worktrees nicht verloren gehen dürfen. Das Muster .runs/ in der .gitignore passt nur auf Verzeichnisse und ignorierte deshalb diesen Link nicht. Am 21. August 2026 zeigte git status ihn in jedem Worktree als nicht versionierte Datei an; es fehlte nur ein git add -A, und er wäre in einem Commit gelandet. Unsere Datenbanktests nutzen außerdem eine gemeinsame Testdatenbank. Damit Tests in zwei Worktrees nicht gleichzeitig laufen, halten wir ein Sperrverzeichnis.

Warum reicht eine Prüfung beim Sitzungsstart nicht?

Beim Öffnen einer Sitzung auf den Zustand des Verzeichnisses zu schauen, hilft, aber nur für diesen Moment. Der Hook zum Sitzungsstart in unserem Repository sagt einer Sitzung, die auf einem sauberen dev startet: „Ein Branch reicht, kein Worktree nötig.“ Starten zwei Sitzungen auf demselben sauberen dev, bekommen beide diese Antwort, und beide legen im selben Verzeichnis einen Branch an. Wechselt die zweite auf ihren neuen Branch, hat sich auch der Branch geändert, auf dem die erste arbeitet.

Deshalb vergleicht ein zweiter Hook, der vor jeder Änderung läuft, Branch und Commit mit dem, was der Sitzung zuletzt gesagt wurde. Details stehen im Beitrag über Hooks; hier wollen wir ergänzen, was verglichen wird. Naheliegend wäre die Zahl der nicht committeten Dateien. Am 12. September 2026 haben wir aber gesehen, dass eine einzige Änderung der Sitzung selbst ein sauberes Verzeichnis unsauber aussehen lässt. Eine Warnung, die darauf schaut, hält die eigene Arbeit des Agenten für die eines anderen. Der Hook schaut deshalb nur auf den Branch und den Commit darunter und warnt, ohne den Vorgang zu stoppen.

Der Hook kann nicht wissen, wer den Wechsel ausgelöst hat, und er versucht auch nicht, es zu erraten. Auch eine Sitzung, die selbst einen Branch anlegt, wird einmal gewarnt, erkennt darin ihr eigenes Tun und macht weiter.

Claude Code führt für eine Sitzung, die in einem Worktree isoliert ist, zusätzlich eigene Prüfungen aus. Laut Dokumentation lehnt es Änderungen ab, die auf einen Pfad im Haupt-Checkout zielen, und Befehle, die Git auf den Haupt-Checkout lenken. Die Dokumentation nennt auch die Grenze: Diese Prüfungen verfolgen nicht, in welche Dateien ein Shell-Befehl schreibt. Ein Befehl, der mit cp oder einer Umleitung in den Haupt-Checkout schreibt, fällt bei diesen Prüfungen nicht auf; laut Dokumentation wird er nach Ihren Berechtigungs- und Sandbox-Einstellungen behandelt. Wohin ein Agent schreiben kann, begrenzt also nicht der Worktree, sondern diese Einstellungen.

Warum sammeln sich Worktrees an, und wie räumt man sie auf?

Einen Worktree anzulegen ist ein einziger Befehl; ihn wieder zu schließen, wird oft vergessen. Wie im Beitrag über Subagenten beschrieben, hatten sich am 27. August 2026 in unserem Repository 41 Worktrees angesammelt, 37 davon aus einer einzigen Review-Runde. Die Unordnung entsteht durch Workflows, nicht durch Menschen. An diesem Tag haben wir ein Aufräumskript geschrieben. Am 18. Oktober 2026 haben wir neu gezählt:

Keiner der 34 Worktrees mit gemergtem Branch hatte nicht committete Änderungen. Genau solche Worktrees entfernt unser Aufräumskript. Das Skript läuft aber nicht von selbst; der Hook zum Sitzungsstart schlägt nur vor, es auszuführen, und bis es jemand tut, bleiben alle liegen. Insgesamt lagen 5 Worktrees im Verzeichnis von Codex (~/.codex/worktrees), die übrigen 61 unter .claude/worktrees/. Nach dem Erstellungsdatum des Verzeichnisses, das Git für jeden Worktree anlegt, waren 28 der noch vorhandenen an einem einzigen Tag entstanden, am 15. Oktober. Auch der Entwurf dieses Beitrags entstand in einem Worktree, der am 18. Oktober 2026 angelegt wurde.

Ob ein Branch gemergt ist, kann Git nicht sagen. Unser Repository mergt Pull Requests per Squash, und ein Squash schreibt die Commits neu. Ein gemergter Branch ist deshalb weder ein Vorfahr von dev, noch stimmen seine Commits eins zu eins überein. Wir haben einen Branch wenige Minuten nach dem Merge geprüft: merge-base --is-ancestor sagte „nicht gemergt“, git cherry „2 Commits fehlen“; beides war falsch. Ein anderer Branch, dessen Inhalt vollständig in dev war, stand bei „36 Commits voraus“. Wissen kann es nur der Pull Request. Deshalb fragt unser Aufräumskript GitHub und entfernt nur saubere Worktrees, deren Pull Request gemergt ist.

Auch die Zahl selbst kann täuschen. Ein Worktree, dessen Verzeichnis von Hand gelöscht wurde, bleibt in der Liste, bis git worktree prune läuft, und ist als prunable markiert. Unser Hook zum Sitzungsstart zählte zuerst alle Zeilen zusammen. Am 8. September 2026 meldete er 26 Worktrees, ein paar Befehle später zeigte git worktree list 7. Heute zählt er lebende und löschbare Einträge getrennt und schlägt das Aufräumskript vor, sobald es mehr als 4 lebende Worktrees oder auch nur einen löschbaren Eintrag gibt.

Auch die Tools räumen unterschiedlich auf. Codex behält standardmäßig seine letzten 15 Worktrees. Cursor behält standardmäßig 25 Worktrees pro Rechner und zählt laut Dokumentation auch Worktrees, die mit git worktree add angelegt wurden, zu den löschbaren. Claude Code räumt Subagent- und Hintergrund-Worktrees weg, lässt aber solche liegen, in denen noch Arbeit steckt. Gemini CLI überlässt das Aufräumen Ihnen. Wenn Sie im selben Repository mehrere Tools nutzen, sollten Sie wissen, welches was löscht.

Worauf sollten Sie achten, wenn Agenten parallel laufen?

Aus jedem Fehler oben ist ein Punkt geworden. Zusammengefasst sieht das so aus:

• Nicht jeder Agent braucht einen Worktree. Ein Worktree ist für den Fall gedacht, dass zwei Arbeiten dasselbe Repository gleichzeitig auf verschiedenen Commits brauchen. Arbeitet eine einzige Sitzung auf einem sauberen dev, reicht ein Branch. Jeder unnötige Worktree ist ein weiteres Verzeichnis, das später aufgeräumt werden muss.
• Vergessen Sie die Einrichtung nicht. Ein neuer Worktree ist ein frischer Checkout: Abhängigkeiten, virtuelle Umgebung und .env fehlen. Auch die Dokumentation von Claude Code und Gemini CLI sagt, dass Sie die Umgebung in jedem neuen Worktree einrichten sollen. In unserem Repository richtet jeder Worktree vor dem ersten Testlauf seine eigene Umgebung ein.
• Teilen Sie die Arbeit nach Dateien auf. In unserem Repository bekamen gleichzeitig laufende Aufgaben getrennte Dateien, jeder Commit lief mit --only, und die Testläufe stellten sich an der gemeinsamen Sperre an.
• Parallelität gibt es nicht umsonst. Laut Dokumentation von Claude Code vervielfacht sich der Token-Verbrauch, wenn mehrere Sitzungen oder Subagenten gleichzeitig laufen.

Am Ende landet die Arbeit paralleler Agenten als Pull Requests auf demselben Branch, und dieser Branch rückt mit jedem Merge weiter. Wenn diffox einen Pull Request prüft, misst es die Änderung ab dem Punkt, an dem sich der Branch vom Basis-Branch getrennt hat (der Merge-Base); das ist die Änderung, die GitHub im Pull Request zeigt. Den vorherigen Stand der Dateien liest es am selben Punkt. Wurde die Arbeit eines anderen Agenten erst später in den Basis-Branch gemergt, mischt sie sich so nicht in dieses Review.