Ein KI-Coding-Agent in einem Projekt ist einfach. Zwei im selben Ordner sind Chaos: Sie bearbeiten dieselben Dateien, teilen sich einen ausgecheckten Branch und überschreiben sich gegenseitig die Arbeit. Git Worktrees sind die eingebaute Lösung, und diese Anleitung zeigt dir, wie du damit mehrere Agenten nebeneinander laufen lässt, jeden auf seinem eigenen Branch, und die Ergebnisse anschließend prüfst und mergst.
Das Wichtigste in Kürze
- Ein Git Worktree ist ein zusätzlicher Arbeitsordner mit eigenen Dateien und eigenem Branch, der sich eine Historie mit dem Repository teilt.
- Lege pro Aufgabe einen Worktree und einen neuen Branch mit git worktree add -b an, kopiere dann die .env und installiere die Abhängigkeiten neu.
- Starte in jedem Worktree einen eigenen Agenten und gib ihm eine eng umrissene Aufgabe in einem anderen Bereich des Codes.
- Prüfe jeden Branch vor dem Mergen mit git log und git diff, entferne dann die Worktrees und lösche die gemergten Branches.
Die Methode funktioniert mit jedem Coding-Agenten, der im Terminal läuft. Jeder Git-Befehl unten wurde mit Git 2.53 ausgeführt und mit der offiziellen git-worktree-Dokumentation abgeglichen, die zuletzt für Git 2.56 aktualisiert wurde.
Warum Agenten getrennte Ordner brauchen
Ein Git Worktree ist ein zusätzlicher Arbeitsordner, der zum selben Repository gehört. Jeder Worktree hat eigene Dateien und einen eigenen ausgecheckten Branch, aber alle teilen sich eine Historie. In den Worten von Git teilt ein verknüpfter Worktree „alles außer den Worktree-spezifischen Dateien wie HEAD, Index usw.“
| Von allen Worktrees geteilt | In jedem Worktree getrennt |
|---|---|
| Commits und Historie | Die Dateien auf der Festplatte |
| Branches und Tags | Der ausgecheckte Branch (HEAD) |
| Repository-Konfiguration | Die Staging-Area (Index) |
Nicht versionierte und ignorierte Dateien wie .env oder node_modules |
Genau diese Aufteilung brauchen parallele Agenten: isolierte Dateien und eine gemeinsame Historie, in die zurückgemergt wird.
Mehrere Tools haben das inzwischen eingebaut. Cursor kann jeden Agenten in einen eigenen Worktree setzen, Codex kann einen Chat in einem starten, und Claude Code hat ein --worktree-Flag. Von Hand braucht es nur ein paar Befehle, funktioniert mit jedem Agenten und zeigt dir, was diese Funktionen unter der Haube machen.

Was du brauchst
- Git. Prüfe es mit
git --version. - Ein Repository mit mindestens einem Commit.
- Einen Coding-Agenten, den du im Terminal starten kannst.
- Speicherplatz für eine zweite (oder dritte) Kopie der Projektdateien und Abhängigkeiten.
Die Beispiele verwenden einen Projektordner namens my-app mit einem Branch main. Setz einfach deine eigenen Namen ein.

Schritt 1: Mit einem sauberen main-Branch starten
Neue Worktrees starten von deinem aktuellen Commit, also committe oder stashe unfertige Arbeit vorher. Im Projektordner:
git status --short
Keine Ausgabe bedeutet, dass der Ordner sauber ist.
Schritt 2: Einen Worktree pro Aufgabe anlegen
Gib jeder Aufgabe einen eigenen Ordner und einen eigenen neuen Branch. Hier gibt es zwei Aufgaben, einen Login-Fix und eine Suchfunktion:
git worktree add -b fix-login ../my-app-login
git worktree add -b add-search ../my-app-search
Erwartete Ausgabe des ersten Befehls:
Preparing worktree (new branch 'fix-login')
HEAD is now at 61730c6 Initial commit
-b fix-login legt einen neuen Branch an, und ../my-app-login ist der Ort für den neuen Ordner: neben deinem Projekt, nicht darin. Prüfe das Ergebnis:
git worktree list
/home/user/code/my-app 61730c6 [main]
/home/user/code/my-app-login 61730c6 [fix-login]
/home/user/code/my-app-search 61730c6 [add-search]
Schritt 3: Jeden Worktree einrichten
Ein neuer Worktree ist ein frischer Checkout. Er enthält nur Dateien, die Git verfolgt, also fehlt alles, was in .gitignore steht: Umgebungsdateien, installierte Pakete, Build-Ausgaben. Kopiere oder erstelle neu, was das Projekt zum Laufen braucht. Wenn es zum Beispiel eine .env-Datei nutzt:
cp .env ../my-app-login/.env
cp .env ../my-app-search/.env
Installiere dann in jedem Worktree die Abhängigkeiten mit deinem üblichen Befehl (npm ci, uv sync usw.). Die Cursor-Doku rät davon ab, Abhängigkeiten per Symlink in einen Worktree zu verlinken, weil das im Hauptordner Probleme verursachen kann. Installiere sie lieber richtig.
Startet das Projekt einen Dev-Server, gib jedem Worktree einen anderen Port, damit sich die Server der Agenten nicht in die Quere kommen.
Schon gewusst?
Ein neuer Worktree enthält nur Dateien, die Git verfolgt. Alles in .gitignore, etwa .env-Dateien und installierte Pakete, fehlt, bis du es kopierst oder neu installierst.
Schritt 4: Einen Agenten pro Worktree starten
Öffne für jeden Worktree einen eigenen Terminal-Tab oder ein eigenes Fenster, wechsle hinein und starte deinen Agenten wie gewohnt. Mit dem Open-Source-Tool Qwen Code zum Beispiel:
cd ../my-app-login
qwen
Mach dasselbe in ../my-app-search in einem zweiten Tab. Jetzt arbeitet jeder Agent in seinem eigenen Ordner, auf seinem eigenen Branch.
Gib jedem Agenten eine eng umrissene Aufgabe mit klarem Ziel. Ein Prompt, der gut funktioniert:
Fix the login bug where a wrong password shows a blank page.
Only change files needed for this fix. Run the tests, and when
they pass, commit your work to the current branch.
Zwei Gewohnheiten sorgen dafür, dass paralleles Arbeiten rund läuft:
- Teile Aufgaben nach Bereichen auf. Zwei Agenten, die dieselbe Datei umschreiben, erzeugen später einen Merge-Konflikt. Wähle Aufgaben, die unterschiedliche Teile des Codes betreffen.
- Pack gemeinsame Regeln in eine versionierte Datei. AGENTS.md ist ein offenes Format für Anweisungen an Coding-Agenten (Setup-Befehle, Test-Befehle, Code-Stil). Committe die Datei, und jeder neue Worktree bekommt automatisch eine Kopie. Unser Ratgeber zu Agent Skills in Claude Code zeigt einen verwandten Weg, Anweisungen zu bündeln.
Schritt 5: Jeden Branch prüfen
Du musst deinen Hauptordner nicht verlassen, um zu sehen, was ein Agent gemacht hat. git -C <path> führt einen Befehl aus, als wärst du in diesem Ordner:
git -C ../my-app-search status --short
?? scratch.txt
Das zeigt eine übrig gebliebene Datei, die der Agent erstellt, aber nicht committet hat. Committe oder lösche solche Reste jetzt, denn Git weigert sich, einen Worktree zu entfernen, der sie noch enthält. So siehst du die Commits und Änderungen, die ein Branch zusätzlich zu main mitbringt:
git log --oneline main..fix-login
git diff --stat main...fix-login
873a385 Fix login
app.py | 1 +
1 file changed, 1 insertion(+)
Lass --stat weg, um den vollständigen Diff zu lesen. Lies ihn gründlich: Ein „fertig“ vom Agenten ist kein Beweis, dass die Änderung stimmt. Ist das Projekt eine Website, kann ein Agent mit Browserzugriff seine Arbeit selbst prüfen, wie in unserem Ratgeber zu Chrome DevTools MCP beschrieben.
Schritt 6: Mergen und aufräumen
Merge jeden fertigen Branch aus deinem Hauptordner:
git merge fix-login
git merge --no-edit add-search
Updating 61730c6..873a385
Fast-forward
app.py | 1 +
1 file changed, 1 insertion(+)
Merge made by the 'ort' strategy.
search.py | 2 ++
1 file changed, 2 insertions(+)
create mode 100644 search.py
Wenn du im Team arbeitest, pushe jeden Branch und öffne einen Pull Request, statt lokal zu mergen. Unser Ratgeber zu SSH-Schlüsseln erklärt den passwortlosen Zugriff auf einen Remote-Server.
Entferne dann die Worktrees und lösche die gemergten Branches:
git worktree remove ../my-app-login
git worktree remove ../my-app-search
git branch -d fix-login add-search
git worktree remove löscht den Ordner, einschließlich ignorierter Dateien darin wie der kopierten .env. Führe git worktree list erneut aus, dann sollte nur noch dein Hauptordner übrig sein.
Schon gewusst?
git worktree remove löscht den ganzen Ordner, auch ignorierte Dateien wie eine kopierte .env, und Git weigert sich, einen Worktree zu entfernen, der noch nicht committete Reste enthält.
Optional: ein Hilfsskript
Sobald die Routine sitzt, spart ein kurzes Skript Tipparbeit. Speichere das als new-task.sh in deinem Projekt, mach es mit chmod +x new-task.sh ausführbar und committe es:
#!/usr/bin/env bash
set -euo pipefail
name="$1"
root="$(git rev-parse --show-toplevel)"
dir="$(dirname "$root")/$(basename "$root")-$name"
git worktree add -b "$name" "$dir"
if [ -f "$root/.env" ]; then
cp "$root/.env" "$dir/.env"
fi
echo "Ready: $dir"
./new-task.sh try-cache legt den Branch try-cache in einem benachbarten Ordner an, kopiert die .env und gibt etwa Folgendes aus:
Preparing worktree (new branch 'try-cache')
HEAD is now at 8bca3c4 Merge branch 'add-search'
Ready: /home/user/code/my-app-try-cache
Typische Fehler und Lösungen
fatal: 'fix-login' is already used by worktree at '...': Ein Branch kann immer nur in einem Worktree ausgecheckt sein. Arbeite in dem Ordner, der ihn schon hat, oder lege mit-beinen neuen Branch an.fatal: '../my-app-search' contains modified or untracked files, use --force to delete it: Der Agent hat nicht committete Arbeit hinterlassen. Committe oder lösche diese Dateien, oder führegit worktree remove --force ../my-app-searchaus, wenn du sicher bist, dass dort nichts Wichtiges liegt.error: cannot delete branch 'add-search' used by worktree at '...': Entferne zuerst den Worktree und lösche dann den Branch.error: the branch 'add-search' is not fully merged:git branch -dschützt nicht gemergte Arbeit. Merge den Branch, oder nutzegit branch -D add-search, um die Arbeit zu verwerfen.git worktree listzeigt einen Ordner mit der Markierungprunable: Der Ordner wurde von Hand gelöscht statt mitgit worktree remove. Führegit worktree pruneaus, um den veralteten Eintrag zu entfernen.- Die App startet in einem Worktree nicht: Ignorierte Dateien wurden nicht kopiert. Erstelle die
.envdort neu und installiere die Abhängigkeiten neu (Schritt 3). - Merge-Konflikte in Schritt 6: Zwei Agenten haben dieselben Zeilen geändert. Löse den Konflikt von Hand, oder führe
git merge --abortaus und lass einen Agenten seine Arbeit auf dem aktualisiertenmainneu machen. fatal: not a git repository: .../.git/worktrees/my-app-loginnachdem du den Hauptordner verschoben oder umbenannt hast: Führegit worktree repairam neuen Ort des Hauptordners aus.- Das Projekt nutzt Submodule: Laut Git-Dokumentation ist die Worktree-Unterstützung für Submodule unvollständig, und mehrere Checkouts eines solchen Projekts werden nicht empfohlen.
Fazit
Worktrees machen aus „ein Agent nach dem anderen“ ein kleines Team: ein Ordner und ein Branch pro Aufgabe, ein kurzer Blick mit git diff, dann Merge und Aufräumen. Fang mit zwei Agenten an unabhängigen Aufgaben an, halte die Prompts eng und prüfe die Diffs vor dem Mergen.
Häufige Fragen
Was ist ein Git Worktree?
Ein zusätzlicher Arbeitsordner, der zum selben Repository gehört. Jeder Worktree hat eigene Dateien auf der Festplatte, einen eigenen ausgecheckten Branch und eine eigene Staging-Area, während sich alle eine Commit-Historie, Branches, Tags und die Repository-Konfiguration teilen.
Können zwei Worktrees denselben Branch nutzen?
Nein. Ein Branch kann immer nur in einem Worktree ausgecheckt sein, und Git stoppt dich mit einem „already used by worktree“-Fehler. Arbeite in dem Ordner, der ihn hat, oder lege mit -b einen neuen Branch an.
Warum startet meine App in einem neuen Worktree nicht?
Ein neuer Worktree enthält nur Dateien, die Git verfolgt, also fehlen ignorierte Dateien wie .env und installierte Pakete. Kopiere die .env hinüber und installiere die Abhängigkeiten in diesem Worktree mit deinem üblichen Befehl neu.
Wie lösche ich einen Git Worktree sicher?
Committe oder lösche übrig gebliebene Dateien, führe dann git worktree remove mit dem Ordnerpfad aus und lösche den gemergten Branch mit git branch -d. Hast du den Ordner von Hand gelöscht, entfernt git worktree prune den veralteten Eintrag.
Kurzes Quiz
Was teilt ein verknüpfter Worktree mit dem Hauptordner?
- Seine Staging-Area
- Die Commit-Historie
- Seinen ausgecheckten Branch
Worktrees teilen sich eine Historie, aber jeder hat eigene Dateien, einen eigenen ausgecheckten Branch und einen eigenen Index.
Welcher Befehl räumt einen Worktree auf, dessen Ordner von Hand gelöscht wurde?
- git worktree prune
- git branch -D
- git merge –abort
git worktree prune entfernt den veralteten Eintrag, den git worktree list als prunable markiert.
Warum sollten parallele Agenten an verschiedenen Bereichen des Codes arbeiten?
- Worktrees können keine Dateien teilen
- Git begrenzt die Zahl der Agenten pro Repository
- Das Bearbeiten derselben Datei führt zu Merge-Konflikten
Die Anleitung warnt, dass zwei Agenten, die dieselbe Datei umschreiben, später einen Merge-Konflikt erzeugen.
Quellen
Links zuletzt geprüft am 15. November 2026.





Kommentar schreiben