Zum Inhalt springen
SONOYA.com
KI

Claude Code parallel nutzen: Git-Worktrees erklärt

So lässt Du mehrere Claude-Code-Sitzungen im selben Repo arbeiten, ohne dass sie sich Dateien überschreiben: mit claude --worktree oder git worktree.

Von

Verzweigungssymbol eines Git-Branches auf dunklem Verlauf als Bild für Git-Worktrees, in denen mehrere Claude-Code-Sitzungen getrennt voneinander arbeiten

Du lässt Claude Code in einem Terminal an einer neuen Funktion arbeiten und willst in einem zweiten Terminal schnell einen Fehler beheben lassen. Beide Sitzungen laufen im selben Projektordner, und plötzlich ändert die eine Sitzung Dateien, die die andere gerade umbaut, oder ein git checkout der einen Sitzung zieht der anderen den Boden unter den Füßen weg. Die saubere Lösung dafür heißt Git-Worktree: Jede Sitzung bekommt ihren eigenen Arbeitsordner mit eigenem Branch, und alle teilen sich trotzdem dieselbe Git-Historie.

Hier erfährst Du, was ein Worktree ist, wie Du ihn mit der eingebauten Option claude --worktree in einem Schritt anlegst, wie Du es von Hand mit git worktree machst und wie Du die Ergebnisse am Ende wieder zusammenführst. Die Git-Befehle habe ich mit Git 2.54 auf macOS in einem Testrepository durchgespielt, die Angaben zu Claude Code stammen aus der offiziellen Seite Run parallel sessions with Git worktrees mit Stand November 2026. Falls Claude Code bei Dir noch nicht läuft, hilft Dir zuerst die Anleitung: Claude Code auf dem Mac installieren & nutzen.

Was ein Worktree ist

Ein normales Git-Repository hat genau einen Arbeitsordner, in dem genau ein Branch ausgecheckt ist. Ein Worktree ist ein zusätzlicher Arbeitsordner, der an dasselbe Repository angeschlossen ist, aber einen anderen Branch ausgecheckt hat. Commits, Branches und Remotes liegen weiterhin nur einmal im gemeinsamen .git-Verzeichnis, deshalb ist ein Worktree in Sekunden angelegt und braucht kaum Platz.

Für Claude Code ist das genau die richtige Trennung. Jede Sitzung sieht nur die Dateien ihres eigenen Ordners, ändert nur ihren eigenen Branch, und ein Commit in einem Worktree ist sofort auch im Hauptordner bekannt, weil die Historie dieselbe ist. Git sorgt außerdem dafür, dass derselbe Branch nicht in zwei Worktrees gleichzeitig ausgecheckt sein kann, sodass sich zwei Sitzungen nicht versehentlich auf demselben Stand in die Quere kommen.

Der schnelle Weg: claude —worktree

Claude Code bringt die Worktree-Verwaltung selbst mit. Wechsle in Deinen Projektordner und starte die Sitzung mit einem Namen für die Aufgabe:

Code
cd ~/projekte/meine-app
claude --worktree login-formular

Claude Code legt damit den Ordner .claude/worktrees/login-formular/ im Projekt an, erstellt dort den neuen Branch worktree-login-formular und startet die Sitzung direkt in diesem Ordner. Statt --worktree kannst Du auch kurz -w schreiben, und wenn Du den Namen weglässt, denkt sich Claude Code selbst einen aus. Für die zweite Aufgabe öffnest Du ein neues Terminalfenster und startest eine weitere Sitzung mit einem anderen Namen:

Code
cd ~/projekte/meine-app
claude --worktree bugfix-export

Beide Sitzungen arbeiten nun vollständig getrennt. Wichtig zu wissen ist der Ausgangspunkt: Laut Doku zweigt der neue Branch standardmäßig vom Standard-Branch des Remotes ab, meist main, und nicht von dem Branch, den Du gerade lokal ausgecheckt hast. Soll der Worktree stattdessen vom aktuellen lokalen Stand ausgehen, setzt Du in der settings.json die Einstellung worktree.baseRef auf "head". Wie diese Datei aufgebaut ist und wo sie liegt, erklärt der Artikel Claude Code Berechtigungen: Modi, Regeln, settings.json.

Damit die Worktree-Ordner im Hauptordner nicht als neue, unversionierte Dateien auftauchen, trägst Du sie einmalig in die .gitignore ein:

Code
.claude/worktrees/

Was beim Beenden passiert

Wenn Du eine Worktree-Sitzung beendest, prüft Claude Code, ob darin noch Arbeit steckt. Hat die Sitzung nichts geändert, wird ein Worktree ohne eigenen Namen samt Branch automatisch entfernt, bei einem benannten Worktree fragt Claude Code nach. Gibt es geänderte Dateien oder neue Commits, fragt es immer, ob der Worktree bleiben oder weg soll. Wählst Du behalten, zeigt Claude Code den Befehl an, mit dem Du später weitermachst, nach dem Muster:

Code
claude --worktree login-formular --resume

Wählst Du entfernen, sind Ordner und Branch samt allen nicht übernommenen Änderungen gelöscht. Committe deshalb vorher, was Du behalten willst. Im nicht interaktiven Modus mit claude -p räumt Claude Code übrigens nichts auf, dort entfernst Du den Worktree selbst, wie weiter unten beschrieben.

.env und Abhängigkeiten in den Worktree holen

Ein Worktree enthält nur Dateien, die in Git versioniert sind. Deine .env, lokale Konfigurationen und der Ordner node_modules fehlen also, und der erste Testlauf scheitert prompt. Für die Konfigurationsdateien kennt Claude Code die Datei .worktreeinclude im Projektwurzelordner. Sie nutzt dieselbe Syntax wie die .gitignore:

Code
.env
.env.local
config/secrets.json

Kopiert werden nur Dateien, die auf ein Muster passen und gleichzeitig von Git ignoriert werden. Versionierte Dateien sind ohnehin schon im Worktree. Die Datei wirkt nur bei Worktrees, die Claude Code selbst anlegt. Legst Du einen Worktree wie im nächsten Abschnitt von Hand an, kopierst Du die .env selbst hinein. Abhängigkeiten installiert Claude Code dagegen nicht automatisch. Bitte Claude in der neuen Sitzung, sie zu installieren, oder erledige es selbst im Worktree-Ordner, bei einem Node-Projekt etwa so:

Code
npm ci

Der manuelle Weg mit git worktree

Wenn Du den Ordner lieber selbst wählst, etwa neben dem Projekt statt darin, oder wenn Du einen bestehenden Branch weiterbearbeiten willst, legst Du den Worktree direkt mit Git an. Im Hauptordner des Projekts erstellt dieser Befehl den Ordner ../meine-app-feature mit dem neuen Branch feature-x:

Code
git worktree add ../meine-app-feature -b feature-x

Git antwortet mit Preparing worktree (new branch 'feature-x') und dem Commit, auf dem der neue Branch steht. Einen schon vorhandenen Branch checkst Du ohne -b aus, also mit git worktree add ../meine-app-fix bugfix-export. Alle weiteren Optionen beschreibt die offizielle Git-Dokumentation zu git worktree. Danach wechselst Du in den neuen Ordner und startest Claude Code ganz normal:

Code
cd ../meine-app-feature
claude

Welche Worktrees es gerade gibt, zeigt Dir dieser Befehl aus jedem der Ordner heraus:

Code
git worktree list

Die Ausgabe nennt pro Zeile den Pfad, den Commit und den Branch in eckigen Klammern, zum Beispiel /Users/du/projekte/meine-app-feature a37899a [feature-x]. Genau daran erkennst Du, dass der Worktree richtig angelegt ist.

Dev-Server und Ports

Zwei Worktrees bedeuten oft auch zwei Dev-Server. Starten beide auf demselben Port, scheitert der zweite mit der Meldung, dass die Adresse schon belegt ist. Gib dem zweiten Server deshalb ausdrücklich einen anderen Port mit, bei Vite-basierten Projekten zum Beispiel so:

Code
npm run dev -- --port 5174

Sag das auch Claude in der jeweiligen Sitzung, damit es beim Testen die richtige Adresse aufruft. Wie Du herausfindest, welcher Prozess einen Port blockiert, steht im Artikel Port belegt am Mac: „Address already in use“ lösen.

Ergebnisse zusammenführen

Ist eine Aufgabe fertig und im Worktree committet, holst Du sie wie jeden anderen Branch nach main. Wechsle dazu in den Hauptordner, in dem main ausgecheckt ist, und führe den Branch zusammen:

Code
cd ~/projekte/meine-app
git merge worktree-login-formular

Arbeitest Du mit GitHub oder einer anderen Plattform, pushst Du den Branch stattdessen aus dem Worktree heraus mit git push -u origin worktree-login-formular und öffnest einen Pull Request. Haben beide Sitzungen dieselbe Stelle einer Datei geändert, meldet Git beim Zusammenführen einen Konflikt. Wie Du den sicher auflöst, zeigt Dir Git-Konflikte lösen: Merge, Rebase und Notbremse. Konflikte lassen sich übrigens am besten vermeiden, indem Du parallele Sitzungen an klar getrennten Teilen des Projekts arbeiten lässt.

Worktrees aufräumen

Einen Worktree, den Du von Hand angelegt hast und nicht mehr brauchst, entfernst Du aus dem Hauptordner mit:

Code
git worktree remove ../meine-app-feature

Stecken darin noch geänderte oder neue Dateien, verweigert Git das mit contains modified or untracked files, use --force to delete it. Das ist ein Schutz: Prüfe mit git -C ../meine-app-feature status, was dort liegt, und nimm --force erst, wenn Du sicher bist, dass nichts davon fehlt. Der Branch selbst bleibt beim Entfernen erhalten. Brauchst Du ihn nach dem Zusammenführen nicht mehr, löschst Du ihn mit git branch -d feature-x.

Typische Fehler und ihre Lösung

fatal: 'main' is already used by worktree at … erscheint, wenn Du einen Branch auschecken willst, der schon in einem anderen Worktree aktiv ist. Ältere Git-Versionen formulieren es als is already checked out at. Git verhindert damit, dass zwei Ordner denselben Branch gleichzeitig verändern. Leg stattdessen mit -b einen neuen Branch an oder arbeite in dem Worktree weiter, den die Meldung nennt.

Worktree-Ordner im Finder gelöscht. Dann kennt Git den Worktree weiterhin, und git worktree list markiert ihn als prunable. Den verwaisten Eintrag räumst Du so auf:

Code
git worktree prune -v

Git meldet dabei gitdir file points to non-existent location für jeden entfernten Eintrag, danach ist der Branch wieder frei für einen neuen Worktree.

Can only use --worktree in a git repository. Die eingebaute Option funktioniert nur in einem Git-Repository mit mindestens einem Commit. Leg in einem neuen Projekt also erst mit git init und einem ersten Commit die Grundlage.

Tests scheitern sofort im neuen Worktree. Meist fehlen .env oder node_modules. Ergänze die .worktreeinclude und installiere die Abhängigkeiten wie oben beschrieben.

Worktrees auch für Subagents

Dasselbe Prinzip nutzt Claude Code auch innerhalb einer Sitzung. Ein Subagent, der in seiner Definition isolation: worktree trägt, bekommt einen eigenen, temporären Worktree und kann dort Dateien ändern, ohne Deinen Arbeitsstand zu berühren. Ändert er nichts, wird der Worktree automatisch wieder entfernt. Wann Subagents sich überhaupt lohnen und wie sie Deinen Kontext entlasten, erklärt Claude Code: Kontext, /compact, /clear und Subagents.

Für den Alltag reicht meist die einfache Regel: eine Aufgabe, ein Worktree, eine Sitzung. Mit claude --worktree <name> ist das ein einziger Befehl, mit .worktreeinclude und einem Eintrag in der .gitignore ist das Projekt dafür einmal vorbereitet, und am Ende führst Du die Branches nacheinander zusammen wie bei jedem anderen Feature.

Weiterlesen.