Git Worktree mit Claude Code und Codex: Praxis-Guide

Lässt du mehr als einen Coding-Agent auf ein Repository los, brauchst du Git Worktrees. Damit arbeitet jeder Agent gleichzeitig auf seinem eigenen Branch, in seinem eigenen Ordner, ohne den anderen in die Quere zu kommen.

Was ist ein Git Worktree?

Ein normaler Clone hat einen Working Tree: einen Ordner, einen ausgecheckten Branch. Ein Worktree ist ein zusätzlicher Arbeitsordner, der am selben Repository hängt und einen anderen Branch ausgecheckt hat. Alle Worktrees teilen sich eine .git-Historie – Commits aus einem sind sofort in allen anderen sichtbar –, ihre Dateien sind aber getrennt.

Für Agents heißt das:

• Claude Code bearbeitet Dateien in ../atlas-auth auf feat/auth
• Codex bearbeitet Dateien in ../atlas-search auf feat/search
• Du prüfst weiter und lässt die App im Hauptordner auf main laufen

Niemand überschreibt die Änderungen eines anderen.

Einen Worktree pro Aufgabe anlegen

Aus dem Hauptordner deines Repositorys:

# new branch + new folder next to the repo
git worktree add ../atlas-auth -b feat/auth
 
# another one, starting from a specific branch
git worktree add ../atlas-search -b feat/search origin/main
 
# see them all
git worktree list

Dann startest du in jedem Ordner einen Agent:

cd ../atlas-auth && claude
cd ../atlas-search && codex

Benenne Worktree-Ordner nach ihrer Aufgabe. In einem Monat sagt dir atlas-auth noch etwas, wt2 nicht.

Oder Claude Code den Worktree anlegen lassen

Neuere Versionen von Claude Code legen den Worktree selbst an:

claude --worktree feature-auth   # or: claude -w feature-auth

Das erstellt einen Worktree unter .claude/worktrees/feature-auth/ auf einem neuen Branch namens worktree-feature-auth und startet Claude darin. Führ den Befehl mit einem anderen Namen in einem zweiten Terminal aus, und du hast eine zweite, isolierte Session. Du kannst Claude auch mitten in einer Session bitten, „in einem Worktree zu arbeiten“.

Ein paar Details aus der Worktree-Dokumentation von Claude Code:

• Nimm .claude/worktrees/ in deine .gitignore auf, damit die Worktree-Dateien in deinem Haupt-Checkout nicht als untracked auftauchen.
• Das Repository braucht mindestens einen Commit.
• Beim Beenden entfernt Claude einen sauberen Worktree (bei einem benannten fragt er vorher) und fragt, ob ein Worktree mit offenen Änderungen bleiben soll.
• Eine .worktreeinclude-Datei listet von Git ignorierte Dateien wie .env, die in jeden neuen Worktree kopiert werden.

Nimm claude --worktree, wenn Claude Code der einzige Agent an der Aufgabe ist. Nimm ein schlichtes git worktree add, wenn du Ordner- und Branch-Namen selbst wählen oder Codex bzw. einen anderen Agent im Worktree laufen lassen willst.

Jeden Worktree vorbereiten, bevor der Agent startet

Ein neuer Worktree enthält nur die Dateien, die Git trackt. Bevor du ihn einem Agent übergibst:

• Abhängigkeiten installieren. node_modules, Virtualenvs und Build-Ordner werden nicht geteilt. Führ in jedem Worktree npm install (oder dein Äquivalent) aus. Paketmanager mit gemeinsamem Store wie pnpm machen das schnell.
• Nicht getrackte Konfiguration kopieren. .env-Dateien und lokale Einstellungen sind meist von Git ignoriert – kopier, was die App zum Laufen braucht. Mit claude --worktree trägst du sie stattdessen in .worktreeinclude ein.
• Unterschiedliche Ports nutzen. Zwei Dev-Server können nicht beide auf Port 3000 lauschen. Starte den zweiten auf einem anderen Port, zum Beispiel PORT=3001 npm run dev.
• Anweisungen über getrackte Dateien teilen. CLAUDE.md und AGENTS.md liegen in Git, also bekommt sie jeder Worktree automatisch.

Prüfen, mergen, aufräumen

Ist ein Agent fertig:

# in the worktree: check the work
git diff main...feat/auth
npm test
 
# in the main folder: merge
git merge feat/auth
 
# remove the worktree folder and its registration
git worktree remove ../atlas-auth
git branch -d feat/auth

Hast du einen Worktree-Ordner von Hand gelöscht, entfernt git worktree prune den verwaisten Eintrag.

Typische Stolperfallen

• „Branch is already checked out.“ Ein Branch kann immer nur in einem Worktree ausgecheckt sein. Leg stattdessen für jeden Worktree einen neuen Branch an.
• Vergessene Worktrees. Alte Worktrees halten Branches am Leben und belegen Speicherplatz. Schau ab und zu mit git worktree list nach.
• Uncommittete Änderungen beim Entfernen. git worktree remove verweigert den Dienst, wenn der Worktree Änderungen hat. Erst committen oder stashen – oder --force, wenn du sie wirklich verwerfen willst.
• Agents, die im Hauptordner editieren. Starte jeden Agent aus seinem Worktree-Ordner heraus, nicht aus dem Root des Repositorys.

Worktrees in Vibe Console

Vibe Console hält Worktrees sichtbar, während Agents darin arbeiten:

• Der Tab Worktrees in der Versionsverwaltung (⌘⇧G) listet jeden Worktree mit seinem Branch, markiert den Haupt-Worktree und alle Detached Checkouts.
• Zieh einen Worktree auf ein Terminal, um seinen Pfad einzufügen, und starte dort mit ⌘K einen Agent.
• Worktree entfernen räumt einen auf, wenn du fertig bist, und verlangt Entfernen erzwingen, wenn er noch lokale Änderungen hat. Der Haupt-Worktree ist geschützt.
• Das Raster zeigt bis zu neun Terminals, sodass der Agent jedes Worktrees seinen eigenen Bereich bekommt. Siehe Agents parallel laufen lassen.

Leg Worktrees wie oben gezeigt mit git worktree add oder claude --worktree an; beide erscheinen sofort in der Liste.

FAQ

Brauchen Worktrees viel Speicherplatz?

Nur für die ausgecheckten Dateien und alles, was du darin installierst. Die Git-Historie wird geteilt.

Worktrees oder separate Clones?

Worktrees. Sie teilen sich eine Historie, Branches und Commits sind also sofort überall verfügbar, und Aufräumen ist ein einziger Befehl.

Können sich zwei Agents einen Worktree teilen?

Nur wenn höchstens einer davon Dateien bearbeitet. Ein Reviewer-Agent, der nur liest, kann sich einen Worktree mit dem Agent teilen, der den Code schreibt.

14 Tage kostenlos testen: Vibe Console herunterladen.