Codex Worktree Praxisguide: Mehrere KI-Coding-Aufgaben parallel entwickeln, ohne das Repo zu verschmutzen

In einem Repository laufen drei Aufgaben gleichzeitig: fix/auth-expired-session, test/payment-webhook und docs/setup-node20. Im main checkout ist git status plötzlich ein Gemisch aus unrelated changes: eine Änderung am Login-Bug, Test-Fixture-Dateien und ein README-Hinweis zu Node 20. Alle drei Änderungstypen liegen in einem checkout, und Sie können nicht mehr sauber erkennen, welcher Teil eigenständig committet werden kann und welcher andere Arbeit beeinflusst.

Das ist kein abstraktes Parallelisierungsproblem. Es ist die konkrete Folge eines verschmutzten Git checkouts. Der Worktree-Modus im Codex app trennt unterschiedliche Aufgaben in eigene Verzeichnisse und branches, damit jede Arbeitslinie einen diff hat, den Sie prüfen, mergen oder zurückrollen können.

Local / Worktree / Cloud: So wählen Sie den passenden Modus

Der Codex app unterstützt drei Ausführungsmodi. Local und Worktree laufen beide auf Ihrem Computer. Die offizielle Dokumentation formuliert es direkt: „Both Local and Worktree threads will run on your computer“. Cloud läuft dagegen in einer Remote-Umgebung.

Der Worktree-Modus passt zu unabhängigen parallelen Aufgaben oder Experimenten. Jeder thread hat ein eigenes Verzeichnis und einen eigenen branch, sodass der main checkout unberührt bleibt. Local ist einfacher, aber sobald mehrere Aufgaben vermischt werden, wird es schwer, commits sauber zu trennen. Cloud verlässt Ihren Rechner vollständig und passt zu CI/CD und Remote-Builds.

Die Auswahlregel: Für eine einzelne Aufgabe nehmen Sie Local, für parallele oder experimentelle Arbeit Worktree, für Remote-Aufgaben Cloud.

Der Worktree-Modus im Codex app im Detail

Worktree-Erstellung und Handoff

Der Ablauf zum Erstellen eines Worktree threads im Codex app:

1. Erstellen Sie einen neuen thread
2. Wählen Sie den Worktree-Modus (der genaue UI-Name kann sich nach dem 18.06.2026 ändern)
3. Wählen Sie einen Start-branch oder arbeiten Sie standardmäßig auf detached HEAD
4. Senden Sie den ersten prompt
5. Codex beginnt in einem isolierten Verzeichnis zu arbeiten

Standardmäßig arbeitet Codex auf detached HEAD. Dadurch kann Codex im worktree weiterarbeiten und erst dann einen branch erstellen, wenn das Ergebnis behalten werden soll. Handoff verschiebt thread und Code zwischen Local und Worktree.

Handoff-Szenarien:

Worktree nach Local: Nach Abschluss der Aufgabe erstellen Sie im worktree zuerst einen branch, falls er noch auf detached HEAD steht. Danach verschieben Sie ihn per Handoff zurück nach Local und mergen ihn oder erstellen einen PR.

Local nach Worktree: Unfertige Arbeit soll in einer isolierten Umgebung weiterlaufen, damit der main checkout nicht verschmutzt.

Handoff ist nicht nur ein Verzeichniswechsel. Es nimmt den aktuellen thread-Kontext, die prompt-Historie und die unfertigen Änderungen mit.

Besonderheiten von Codex-managed worktrees

Codex-managed worktrees haben einige besondere Eigenschaften:

Standardort: $CODEX_HOME/worktrees

Standardaufbewahrung: 15 worktrees laut Dokumentation vom 18.06.2026; ältere worktrees können automatisch bereinigt werden

Permanent worktree: Manuell erstellte worktrees werden nicht automatisch gelöscht

Branch-Einschränkung: Git erlaubt nicht, denselben branch gleichzeitig in mehreren worktrees auszuchecken. Ein Versuch führt zu einem Fehler

Regelvererbung: AGENTS.override.md wird automatisch in den worktree kopiert, damit Projektregeln konsistent bleiben

Praktisch bedeutet das: Die Anzahl der worktrees ist begrenzt, ältere verwaltete worktrees können bereinigt werden, derselbe branch kann nicht parallel genutzt werden, und Projektregeln werden übernommen.

.worktreeinclude löst Probleme mit ignored files

Worktrees übernehmen standardmäßig nur Git tracked files. Dateien aus .gitignore werden bei Handoff nicht automatisch mitgenommen. Häufig fehlen .env, .env.local, Abhängigkeits-Caches oder lokale Konfigurationsdateien.

Die Lösung: Legen Sie im Projekt-Root eine .worktreeinclude-Datei an und listen Sie darin die ignored files, die kopiert werden sollen. Beispiel:

.env
.env.local
node_modules/.cache

Damit können die dort gelisteten Dateien bei Handoff ebenfalls in den worktree kopiert werden.

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

Setup scripts: Damit das Projekt im worktree läuft

Ein worktree liegt in einem anderen Verzeichnis. Daher können Abhängigkeiten oder nicht eingecheckte Dateien fehlen. Setup scripts laufen beim Erstellen eines neuen worktrees oder beim Start eines neuen threads und machen die Umgebung nutzbar.

Konfigurationsschritte:

1. Setup steps in den Local environments des Codex app konfigurieren
2. Ein .codex-Verzeichnis für Konfigurationsdateien anlegen
3. Plattformspezifische Skripte schreiben

Beispiel für ein Node.js-Projekt:

# .codex/setup.sh
npm install
npm run build

Beispiel für ein Python-Projekt:

# .codex/setup.sh
pip install -r requirements.txt
python manage.py migrate

Setup scripts laufen für jeden neu erstellten worktree automatisch. Das vermeidet manuelle Installationsschritte. Beachten Sie aber, dass UI und Dateiformat sich nach dem 18.06.2026 ändern können; prüfen Sie die aktuelle Dokumentation.

Auch ohne Codex app: Plain Git worktree isoliert ebenfalls

Wenn Sie lieber über CLI oder Terminal arbeiten, können Sie direkt mit Git worktree isolierte Verzeichnisse erstellen und Codex im jeweiligen Verzeichnis starten. Sie brauchen dann keine Verwaltung durch den Codex app, müssen aber alles selbst steuern.

Häufige Git worktree-Befehle:

# Neuen worktree und branch erstellen, im Stil des offiziellen Use Case
git worktree add ../analysis-highway-eda -b analysis/highway-eda

# Neuen worktree auf Basis eines bestehenden branch erstellen
git worktree add ../task-b existing-branch

# Alle worktrees auflisten
git worktree list

# Worktree entfernen
git worktree remove ../task-a

# Veraltete worktree-Metadaten bereinigen
git worktree prune

Vergleich zwischen Codex-managed und Plain Git:

Plain Git worktree passt zu Entwicklern, die die CLI bevorzugen. Allerdings müssen Sie Installation von Abhängigkeiten, Umgebungssetup und Cleanup selbst übernehmen. Codex-managed worktrees automatisieren mehr davon.

Sollten Automations im Hintergrund worktrees nutzen?

Automations in einem Git-Repository können im local project oder in einem dedicated background worktree laufen. Die Wahl hängt von Aufgabentyp und Risikokontrolle ab.

Entscheidungslogik:

Local eignet sich für einmalige Aufgaben und temporäre Tests. Es bearbeitet den main checkout direkt, sodass unfertige Arbeit verschmutzt werden kann. Wenn Sie gerade eine Datei bearbeiten, kann eine background automation dieselbe Datei verändern.

Worktree eignet sich für wiederholte oder geplante Aufgaben. Es trennt automation changes von unfinished local work. Die automation läuft in einem eigenen Verzeichnis und beeinflusst den main checkout nicht.

Risikohinweise:

Automations verwenden die default sandbox settings, die sich nach dem 18.06.2026 ändern können

Unter full access sind Hintergrund-automations riskanter, daher sollten sie worktrees verwenden

Wiederkehrende Hintergrundaufgaben sollten nicht direkt in Local laufen

Die Regel: Einmalige temporäre Aufgaben können Local nutzen. Wiederholte Aufgaben und Hintergrundarbeit mit full access gehören in Worktree.

Welche Aufgaben parallel passen und welche seriell bleiben müssen

Offizielle Use Cases empfehlen, unterschiedliche Explorationen in separate worktrees aufzuteilen. In der Praxis müssen Sie trotzdem Dateikonflikte und Abhängigkeiten prüfen.

Entscheidungstabelle für parallele Aufgaben:

Regeln für Parallelität:

Beginnen Sie mit zwei kleinen unabhängigen Aufgaben, nicht direkt mit fünf oder sechs.

Begrenzen Sie die Anzahl der Aufgaben auf 3-4, um Review-Kosten zu senken.

Jede Aufgabe braucht ein klares Verifikationsziel.

Übertreiben Sie die Parallelisierung nicht. Je mehr parallele Aufgaben Sie starten, desto höher werden Review-Kosten und Merge-Konfliktrisiko.

Task-Card-Template: Was jeder worktree tun soll

Vor dem Start eines worktree sollten Sie die Aufgabe klar beschreiben. Das macht Review und Nachverfolgung einfacher.

Beispiel für eine Task Card:

Goal: "Den session expired bug im auth-Modul beheben"
Context:
  - "Die Session läuft nach 30 Minuten ab, aber das Frontend zeigt keinen Hinweis"
  - "Relevante Dateien: src/auth/session.js, src/components/AuthProvider.jsx"
Constraints:
  - "Datenbank-schema nicht ändern"
  - "Keine neue Abhängigkeit hinzufügen"
Done when:
  - "Das Frontend zeigt einen Hinweis, wenn die Session abläuft"
  - "npm test besteht"
  - "Der Login-Flow wurde manuell getestet"

Branch/Worktree: "fix/auth-expired-session"
Verifikationsbefehl: "npm test && npm run lint"

Ausfüllhinweise:

Goal: Ziel in einem Satz beschreiben

Context: Kontext zu Dateien, Modul und Hintergrund geben

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

Constraints: Grenzen festlegen, also auch was nicht geändert werden darf

Done when: überprüfbare Abschlusskriterien nennen

Branch/Worktree: Klar benennen, etwa task-type/module-description

Verifikationsbefehl: Einen konkret ausführbaren Befehl angeben

So hat jeder worktree eine klare Grenze. Beim Review prüfen Sie das Ergebnis gegen Done when.

Merge-Queue: Nacheinander reviewen, testen und mergen

Wenn parallele Aufgaben fertig sind, sollten Sie nicht alle Ergebnisse auf einmal in main schieben. Sortieren Sie sie nach Risiko und reviewen, testen und mergen Sie sie nacheinander.

Schritte der Merge-Queue:

1. Worktrees nach Risiko sortieren, das kleinste Risiko zuerst
2. Für den ersten worktree:
   • Verifikationsbefehl ausführen: Tests, lint oder beides
   • diff prüfen und Änderungsumfang bestätigen
   • Branch erstellen, falls der worktree noch auf detached HEAD steht
   • diff nach Ihren PR-Review-Regeln prüfen
3. In Local mergen oder PR erstellen:
   • Local merge: per Handoff zurück nach Local, danach merge
   • PR merge: PR erstellen, CI und Review abwarten
4. Für den nächsten worktree dieselben Schritte wiederholen
5. Nach Abschluss aller Aufgaben in den main branch mergen

Verifikationscheckliste:

Verifikationsbefehle bestehen: Tests und lint

Diff-Prüfung: Der Änderungsumfang passt zur Aufgabe

Review guidelines: Keine sensitive files und keine hard-coded secrets

CI besteht, falls vorhanden

Manueller Testflow ist abgeschlossen

Risikohinweise:

Versprechen Sie nicht, dass mehrere worktree-Ergebnisse automatisch gemergt werden

Wenn mehrere Aufgaben dieselbe Datei ändern, lösen Sie Konflikte manuell

Behalten Sie menschliches Review und Tests bei

Der Zweck einer Merge-Queue ist, jede Arbeitslinie reviewbar und rücksetzbar zu halten, nicht alles auf einmal zu committen.

Troubleshooting-Checkliste

Fehler „branch already used by worktree“

Ursache: Der branch wird bereits von einem anderen worktree genutzt.

Lösung:

Mit git worktree list prüfen, welche branches belegt sind.

Einen anderen branch wählen oder den worktree entfernen, der diesen branch belegt.

Code läuft im worktree nicht

Ursache: Abhängigkeiten oder Konfigurationsdateien fehlen.

Prüfschritte:

Prüfen Sie, ob .env und .env.local vorhanden sind. Sie wurden möglicherweise nicht kopiert.

Prüfen Sie, ob Abhängigkeiten installiert sind, etwa node_modules oder venv.

Prüfen Sie, ob Konfigurationsdateien vollständig sind.

Lösung:

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

.worktreeinclude konfigurieren, um ignored files zu kopieren.

Setup scripts konfigurieren, um Abhängigkeiten automatisch zu installieren.

Worktree-Speicherplatz wächst stark

Ursache: Häufige automations erstellen viele worktrees.

Lösung:

Automations runs archivieren, die Sie nicht mehr brauchen.

Manuell git worktree prune ausführen, um stale worktrees zu bereinigen.

Retention-Einstellungen im Codex app prüfen; diese können sich nach dem 18.06.2026 ändern.

Vom agent erstellte worktrees passen nicht zum UI/thread context

Ursache: Ein agent kann worktrees erstellen, ohne den App UI-Pfad zu durchlaufen.

Lösung:

Mit git worktree list alle worktrees prüfen.

Im app die Bindung zwischen thread und worktree manuell kontrollieren.

Vermeiden Sie, den agent worktrees automatisch erstellen zu lassen. Erstellen Sie sie stattdessen über die App UI.

Der wichtigste Troubleshooting-Schritt ist, zuerst mit git worktree list den worktree-Zustand zu prüfen und danach nach Fehlertyp zu handeln.

Kostenabwägung: Parallele Aufgaben verbrauchen schneller quota

Parallele Aufgaben verbrauchen tendenziell mehr turns oder quota. Jeder worktree ist eine eigene session, und Codex rechnet jede session separat.

Kostenregeln:

Halten Sie parallele Aufgaben auf etwa 3-4 begrenzt.

Beginnen Sie mit zwei kleinen unabhängigen Aufgaben, um Review-Kosten zu senken.

Geben Sie jeder Aufgabe ein klares Verifikationsziel, damit sie nicht endlos iteriert.

Konkrete Preise, quota und plan-Details gehören in einen späteren Cost-&-Quota-Artikel. Diese Seite wiederholt keine unbestätigten Zahlen.

Nächste Schritte und weiterführende Lektüre

Upstream-Artikel:

Codex-Einstiege: kurze Einführung in Local / Worktree / Cloud

AGENTS.md-Projektregeln: wie jeder worktree dieselben Projektregeln erbt