Mehrere KI-Coding-Agenten parallel laufen lassen mit Git Worktrees

Gib jedem KI-Coding-Agenten mit Git Worktrees einen eigenen Ordner und Branch, dann prüfen, mergen und aufräumen. Befehle zum Kopieren und Lösungen für typische Fehler.

Graphic of a tree with three branches, each holding a folder and a small robot at a terminal, for a guide to Git worktrees with AI coding agents

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 geteiltIn jedem Worktree getrennt
Commits und HistorieDie Dateien auf der Festplatte
Branches und TagsDer ausgecheckte Branch (HEAD)
Repository-KonfigurationDie 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.

Vergleich: was Git Worktrees teilen, etwa Historie und Branches, und was jeder getrennt behält

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.

Ablaufdiagramm in fünf Schritten, um mehrere KI-Coding-Agenten parallel mit Git Worktrees laufen zu lassen

Schritt 1: Mit einem sauberen main-Branch starten

Neue Worktrees starten von deinem aktuellen Commit, also committe oder stashe unfertige Arbeit vorher. Im Projektordner:

Terminal
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:

Terminal
git worktree add -b fix-login ../my-app-login
git worktree add -b add-search ../my-app-search

Erwartete Ausgabe des ersten Befehls:

Code
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:

Terminal
git worktree list
Code
/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:

Code
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:

Terminal
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:

Code
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:

  1. 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.
  2. 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:

Terminal
git -C ../my-app-search status --short
Code
?? 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:

Terminal
git log --oneline main..fix-login
git diff --stat main...fix-login
Code
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:

Terminal
git merge fix-login
git merge --no-edit add-search
Code
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:

Terminal
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:

Code
#!/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:

Code
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 -b einen 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ühre git worktree remove --force ../my-app-search aus, 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 -d schützt nicht gemergte Arbeit. Merge den Branch, oder nutze git branch -D add-search, um die Arbeit zu verwerfen.
  • git worktree list zeigt einen Ordner mit der Markierung prunable: Der Ordner wurde von Hand gelöscht statt mit git worktree remove. Führe git worktree prune aus, um den veralteten Eintrag zu entfernen.
  • Die App startet in einem Worktree nicht: Ignorierte Dateien wurden nicht kopiert. Erstelle die .env dort 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 --abort aus und lass einen Agenten seine Arbeit auf dem aktualisierten main neu machen.
  • fatal: not a git repository: .../.git/worktrees/my-app-login nachdem du den Hauptordner verschoben oder umbenannt hast: Führe git worktree repair am 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.

Von Mindloop Editorial

The Mindloop Experience editorial team writes clear, carefully sourced explainers and how-tos on tech, science, money and culture, for anyone who likes to know how things actually work.

Über Mindloop Experience

Kommentare

Kommentar schreiben

Mehr von Mindloop Experience

Alle Artikel von Mindloop Experience

Du kannst bis zu 50-mal applaudieren.