Nethür
Anmelden
macOS demnächst

Blog · 5. November 2026

Claude-Code-Worktrees erklärt

Ein verständlicher Guide zu git worktrees in Claude Code: was sie isolieren, wo sie liegen und wie du sie anlegst, reviewst und entfernst, ohne Arbeit zu verlieren.

Diagramm: ein main-Branch teilt sich in drei Nethür-Worktrees auf, einen pro Aufgabe

Ein Claude-Code-Worktree ist ein ganz normaler git worktree, in dem du Claude Code laufen lässt. Git checkt eine zweite Kopie des Repositorys auf einem anderen Branch aus, Claude Code nutzt dieses Verzeichnis als Working Tree, und dein Haupt-Checkout bleibt unberührt. Der Speicherort ist der Pfad, den du an `git worktree add` übergibst — oder das verwaltete Verzeichnis des Tools, das ihn für dich anlegt.

„Claude-Code-Worktree“ klingt nach einem Feature, das du aktivieren musst. Meist ist es simpler: Ein Worktree ist ein Verzeichnis, das git anlegt, und Claude Code ist ein Prozess, der Dateien in dem Verzeichnis bearbeitet, in dem du ihn startest. Setz diese beiden Fakten zusammen, und du hast isolierte Agenten-Sessions.

Diese Unterscheidung ist wichtig, weil im Netz drei verschiedene Dinge durcheinandergehen: git worktrees, die Worktree-Funktionen in Claude Codes eigenen Apps und Arbeitsbereich-Tools, die Worktrees für dich anlegen. Sie teilen Name und Zweck, aber Speicherort, Aufräumen und Review unterscheiden sich je nachdem, wer das Verzeichnis erstellt hat.

Was ein git worktree wirklich ist

Ein normaler Clone hat einen Working Tree: die Dateien, die du im Editor siehst. Ein git worktree erlaubt demselben Repository mehrere Working Trees gleichzeitig, jeder auf einem anderen Branch. Objektdatenbank und Remotes werden geteilt; die ausgecheckten Dateien und der Index nicht.

git worktree list
# /Users/you/app             abc1234 [main]
# /Users/you/app-fix-login   def5678 [fix/login]
  • Jeder Worktree hat seinen eigenen Branch, HEAD, Index und eigene Dateien auf der Platte.
  • Du kannst denselben Branch nicht in zwei Worktrees gleichzeitig auschecken.
  • Einen Worktree zu löschen entfernt das Verzeichnis und seinen Checkout, nicht die Branch-Historie.
  • Jeder Worktree gehört weiterhin zum selben Repository, deshalb sehen Commits, Fetches und Pushes dieselben Objekte.

Genau diese Isolation braucht ein Agent. Claude Code kann in seinem Worktree lesen, bearbeiten, Tests ausführen und committen, ohne den Checkout anzufassen, den du offen hast. Wenn der Agent etwas kaputt macht, löschst du das Verzeichnis und behältst deinen Haupt-Branch.

Warum Claude Code von einem Worktree profitiert

Eine Agenten-Session ist kein Chat, der zufällig Dateien anfasst. Sie führt Befehle aus, startet Dev-Server, schreibt generierte Dateien, staged Änderungen und wechselt manchmal Branches. Zwei Sessions in einem Checkout teilen all diesen Zustand. Der Fehler ist selten dramatisch: Ein Test besteht gegen den falschen Code, ein Formatter schreibt die Arbeit des anderen Agenten um, oder ein Commit enthält Dateien aus beiden Aufgaben.

Ein Worktree verwandelt diese Shared-State-Fehler in getrennte Verzeichnisse. Der Preis: Jeder neue Worktree startet sauber — keine node_modules, keine .env, keine lokale Datenbank. Der Rest dieses Guides dreht sich vor allem darum, diesen Preis bewusst zu zahlen.

Gibt es in Claude Code einen Worktree-Modus?

Die Claude-Code-CLI braucht keinen speziellen Modus, um in einem Worktree zu arbeiten. Ihre Session-Grenze ist das Arbeitsverzeichnis. Starte claude in ../app-fix-login, und die Session liest und schreibt dort; starte eine weitere in ../app-fix-billing, und sie hat einen anderen Branch und einen anderen Satz Dateien.

Andere Claude-Code-Oberflächen verwalten Worktrees für dich. Die Desktop-App kann parallele Sessions in isolierten git worktrees ausführen, und Agenten-Teams oder Subagenten können Arbeit innerhalb einer Session delegieren. Das sind Komfortschichten: Sie legen einen Checkout an, setzen den Agenten hinein und verbergen den Pfad. Wenn du einen vorhersehbaren Speicherort brauchst, leg den Worktree selbst an und starte Claude Code darin.

Wo sollte ein Claude-Code-Worktree liegen?

Der Speicherort hängt davon ab, wer den Worktree anlegt. Bei einem manuellen Setup übergibst du einen Pfad an git worktree add. Zwei Konventionen funktionieren gut: ein Geschwisterverzeichnis neben dem Haupt-Checkout oder ein eigener worktrees/-Ordner außerhalb des Repositorys.

# sibling next to the main checkout
git worktree add ../app-fix-login -b fix/login origin/main

# or a dedicated root outside the repo
git worktree add ~/worktrees/app/fix-login -b fix/login origin/main

Halte Worktrees außerhalb des Haupt-Checkouts. Ein Worktree innerhalb des Repositorys taucht in jeder Suche auf, verwirrt das Indexing im Editor und kann versehentlich committet werden. Wenn ein Tool Worktrees in einem versteckten Ordner im Repo anlegt, prüfe, ob dieser Ordner gitignored ist, bevor du dich darauf verlässt.

Nethür legt Worktrees in seinem eigenen verwalteten Verzeichnis an und verfolgt den Pfad für dich. Wenn du bereits Worktrees von Claude Code, GSD oder einem einfachen git worktree add hast, kann Nethür sie als externe Worktrees anzeigen, statt dich zu bitten, sie zu verschieben. Einstellungen → Allgemein → Arbeitsbereich legt fest, welche externen Quellen sichtbar sind und welche Speicherort-Wurzeln gescannt werden.

Wenn du Pfade nicht von Hand verwalten willst, kann eine git-worktree-GUI wie Nethür Worktrees für dich anlegen, verfolgen und aufräumen — und trotzdem bleibt ein normaler Checkout auf der Platte.

Einen Worktree anlegen und Claude Code starten

Starte von einem aktuellen Basis-Ref, damit der Agent nicht gegen den Code von letzter Woche arbeitet.

git fetch origin
git worktree add ../app-fix-login -b fix/login origin/main
cd ../app-fix-login
claude

Nutze einen eindeutigen Branch-Namen pro Worktree. Wenn du einen zweiten Agenten auf dieselbe Aufgabe setzen willst, lege einen zweiten Worktree mit einem anderen Branch an, selbst wenn der Prompt identisch ist. Der Branch ist das, was die beiden Ergebnisse vergleichbar und unabhängig mergebar macht.

In Nethür ist derselbe Schritt ein Dialog: Worktree anlegen, Aufgabe benennen, Start-from-Ref wählen und Agenten auswählen. Nethür führt git fetch und git worktree add im Hintergrund aus, zeigt den Arbeitsbereich während der Erstellung und öffnet den Agenten im neuen Checkout. Die Worktree-Dokumentation deckt den Start-from-Picker, Ordner-Arbeitsbereiche und verknüpfte Issues ab.

Abhängigkeiten, Env-Dateien und Ports

Ein frischer Worktree ist ein sauberer Checkout — ihm fehlt alles, was git ignoriert. Es gibt drei Wege, damit umzugehen, und die meisten Teams nutzen am Ende alle drei.

  • Pro Worktree installieren. Korrekt und einfach, aber langsam und speicherhungrig, wenn jeder Agent seine eigenen node_modules braucht.
  • Die schweren, neu baubaren Verzeichnisse teilen. Nethürs Worktree Shared Paths materialisieren gitignorierte Verzeichnisse aus dem primären Checkout, mit worktree.sharedDirectories in nethur.yaml für Definitionen auf Repo-Ebene.
  • Die kleinen, worktree-spezifischen Dateien kopieren. .worktreeinclude listet gitignorierte Dateien und Verzeichnisse zum Kopieren, etwa .env oder lokale Editor-Einstellungen, damit jeder Worktree seine eigene Kopie besitzt.
# nethur.yaml at the repo root
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude at the repo root
.env
.env.local
.vscode/settings.json

Ports verdienen eine eigene Regel. Wenn zwei Agenten denselben Dev-Server starten, scheitert der zweite — oder, schlimmer, verbindet sich mit der Datenbank des ersten. Schreib Port und Datenbanknamen in eine Env-Datei pro Worktree, oder lass den Setup-Hook sie aus dem Worktree-Namen ableiten.

Den Diff reviewen, dann den Worktree entfernen

Reviewe jeden Worktree gegen den Ref, von dem er gestartet ist — nicht gegen das, was gerade zufällig auf main liegt. So bleibt der Diff auf die Arbeit des Agenten fokussiert. Nethür zeigt den Diff pro Arbeitsbereich, unterstützt Inline-Anmerkungen und kann Review-Notizen an den Agenten zurückschicken, bevor du committest.

Wenn die Arbeit gemergt ist, entferne den Worktree und den Branch. Lösche das Verzeichnis nicht von Hand: git führt Metadaten unter .git/worktrees, und ein manuelles rm -rf hinterlässt einen veralteten Eintrag.

git worktree remove ../app-fix-login
git branch -d fix/login

# if git refuses because the branch has unmerged commits
git worktree remove --force ../app-fix-login

Git kann einen lokalen Branch mit ungemergten Commits behalten, auch nachdem der Worktree weg ist. Das ist ein Sicherheitsnetz, kein Bug. Nethür zeigt behaltene Branches in einem Review-Schritt, damit du entscheiden kannst, welche du mit Force löschst, statt sie später suchen zu müssen.

Häufige Worktree-Fehler

  • Denselben Branch in zwei Worktrees auschecken. Git verweigert es; wähle einen anderen Branch für den zweiten Agenten.
  • Den Worktree im Repo platzieren. Suchen und Editoren sehen doppelte Dateien, und das Verzeichnis kann committet werden.
  • Eine gemeinsame .env teilen, die auf die Hauptdatenbank zeigt. Jeder Agent sollte eine eigene Datenbank oder ein eigenes Schema bekommen, wenn Migrationen im Spiel sind.
  • Den Basis-Ref vergessen. Ein Worktree von einem veralteten lokalen Branch erzeugt einen verwirrenden Diff und einen schmerzhaften Merge.
  • Dutzende Worktrees nach dem Experiment offen lassen. Räum die Branches auf, solange du noch weißt, welcher gewonnen hat.

Worktrees im Team

Auf einem Team-Server sind Worktrees keine privaten Verzeichnisse mehr. Sie sind gemeinsamer Projektzustand: Ein Teammitglied kann sehen, dass ein Worktree existiert, wer ihn angelegt hat, welcher Agent läuft und ob er blockiert ist. Diese Sichtbarkeit macht die Übergabe von Arbeit sicher.

Nethür behält dasselbe Worktree-Modell, egal ob es auf deinem Laptop, dem Rechner eines Teammitglieds, einem VPS oder einem SSH-Ziel läuft. Der Agent läuft dort, wo der Checkout liegt, und der Client rendert nur die Session. Wenn du die Team-Version dieses Setups willst, lies Claude Code für Teams.

Probier es mit einer Aufgabe aus

Lege einen Worktree für eine kleine Änderung an, starte Claude Code darin und lass deinen Haupt-Checkout daneben offen. Sobald du siehst, dass sich die beiden Sessions nicht mehr stören, fühlt sich das zusätzliche Verzeichnis nicht mehr wie Overhead an. Der Guide für parallele Agenten zeigt, wie du das auf mehrere Agenten skalierst und ihre Ergebnisse vergleichst.

Setz die Anleitung in die Praxis um.

Lade Nethür herunter und starte deinen ersten parallelen Agenten in wenigen Minuten — oder richte einen Team-Arbeitsbereich auf einer Maschine ein, die dir schon gehört.