Git worktree w Claude Code: sesje równoległe

Praktyczne informacje o korzystaniu z Ailoot znajdziesz w dokumentacji.

Czym jest git worktree w Claude Code?#

Uruchamianie kilku agentów równolegle w tym samym folderze to podstawowy problem vibe-codingu w tempie roku 2026. Agenci AI piszą kod szybciej, niż człowiek jest w stanie śledzić, kto nad czym pracuje. Bez izolacji plików uruchomienie dwóch równoległych sesji Claude Code w jednym katalogu kończy się nadpisaniem pracy jednej sesji przez drugą.

Git worktree rozwiązuje ten problem na poziomie systemu plików. Masz jeden główny katalog, w którym pracujesz. Polecenie claude --worktree feature-auth tworzy folder .claude/worktrees/feature-auth/ w osobnej gałęzi i uruchamia w nim Claude Code. Pliki są odizolowane. Zmiany z jednej sesji nie są widoczne w drugiej, dopóki jawnie ich nie scalą.

Oficjalna dokumentacja Anthropic ujmuje to tak:

Wskazówka do samodzielnej oceny: jeśli zdarzyło ci się dostać commit, w którym połowa plików była czyjąś pracą, potrzebujesz worktree.

Czym git worktree różni się od zwykłej gałęzi#

Standardowy przebieg pracy z Gitem wygląda tak: jesteś w gałęzi main i uruchamiasz git checkout feature-x — Git nadpisuje pliki w kopii roboczej. Uruchomione npm run dev przestaje działać, bo zmienił się plik package.json. Odkładasz niezatwierdzone zmiany za pomocą stash i czekasz, aż IDE ponownie zaindeksuje pliki. Wracasz do poprzedniej gałęzi, wszystko znów zostaje nadpisane, więc ponownie musisz wykonać stash i pop.

Git worktree daje inną możliwość: zamiast przełączać jeden folder między gałęziami, tworzysz drugi folder dla innej gałęzi. Polecenie git worktree add ../project-feature-x feature-x tworzy katalog ../project-feature-x/ z plikami z gałęzi feature-x. Gałąź main pozostaje w pierwotnym folderze, a serwer deweloperski nadal działa.

Wcześniej tryb worktree w Claude Code trzeba było konfigurować ręcznie: git worktree add, potem cd, a następnie claude — i powtarzać to w każdym terminalu. Flaga --worktree (dostępna też jako -w) wykonuje te trzy kroki jednym poleceniem.

Uruchom pierwszą równoległą sesję: flaga --worktree#

Minimalny przykład. Otwórz pierwszy terminal w katalogu głównym projektu:

claude --worktree feature-auth

Claude Code wykona trzy czynności:

1. Utworzy .claude/worktrees/feature-auth/ ze snapshotem origin/HEAD (zwykle twojej domyślnej gałęzi).
2. Utworzy nową gałąź worktree-feature-auth.
3. Uruchomi sesję w tym folderze.

Otwórz drugi terminal w tym samym katalogu głównym repozytorium:

claude --worktree bugfix-123

Gotowe. Dwie sesje Claude Code, różne pliki na dysku i różne gałęzie Gita. Jeśli w pierwszej napiszesz obsługę uwierzytelniania, a w drugiej naprawisz nieudany test, fizycznie nie będą mogły sobie przeszkadzać.

Jeśli nie chcesz wpisywać nazwy, Claude sam ją wymyśli:

claude --worktree
# → tworzy coś w rodzaju .claude/worktrees/bright-running-fox/

Wskazówka dla początkujących użytkowników Gita: dodaj .claude/worktrees/ do .gitignore. W przeciwnym razie po uruchomieniu git status w głównym folderze zobaczysz zawartość wszystkich worktree jako nieśledzone pliki:

# .gitignore
.claude/worktrees/

Pułapka, której należy unikać: przed pierwszym uruchomieniem --worktree w nowym katalogu wejdź do niego za pomocą zwykłego claude (bez flagi) i zaakceptuj okno dialogowe zaufania do obszaru roboczego. Jeśli tego nie zrobisz, flaga zakończy działanie błędem „trust not accepted” — również wtedy, gdy połączysz ją z -p w trybie bez interakcji.

Gdzie znajdują się worktree i jak je znaleźć#

Domyślna lokalizacja jest stała: .claude/worktrees/<value>/ w katalogu głównym repozytorium. Jeśli twój projekt znajduje się w ~/dev/my-app/, worktree feature-auth będzie w ~/dev/my-app/.claude/worktrees/feature-auth/.

W przypadku niestandardowych układów (na przykład gdy chcesz umieścić worktree poza repozytorium) dostępny jest hook WorktreeCreate — więcej na ten temat poniżej, w sekcji o SVN i Mercurial.

W ramach jednej sesji Claude możesz przełączyć się do innego istniejącego worktree. Wystarczy napisać na czacie: „przełącz się do .claude/worktrees/bugfix-123”, a Claude wywoła narzędzie EnterWorktree. Bieżący folder pozostanie nietknięty — możesz wrócić w ten sam sposób.

Standardowe polecenie Gita wyświetla listę wszystkich worktree, w tym głównego oraz utworzonych ręcznie:

git worktree list

Wynik będzie wyglądać tak:

/home/user/dev/my-app                  abc1234 [main]
/home/user/dev/my-app/.claude/worktrees/feature-auth  def5678 [worktree-feature-auth]
/home/user/dev/my-app/.claude/worktrees/bugfix-123    9876fed [worktree-bugfix-123]

Kopiowanie .env i sekretów: plik .worktreeinclude#

Gdy --worktree tworzy nowy folder, trafiają do niego tylko pliki zatwierdzone w Gicie. .env z kluczami API i .env.local z lokalną konfiguracją znajdują się w .gitignore, więc nie ma ich w worktree. W rezultacie pierwsze npm run dev kończy się błędem „MISSING DATABASE_URL”.

Domowe rozwiązanie polega na ręcznym kopiowaniu .env po każdym użyciu --worktree. Raz zadziała, a potem się o tym zapomina. Rozwiązaniem Anthropic jest plik .worktreeinclude w katalogu głównym projektu, w którym wymienia się pliki ignorowane przez Git do automatycznego kopiowania do każdego nowego worktree.

Utwórz plik .worktreeinclude w katalogu głównym repozytorium:

.env
.env.local
config/secrets.json

Składnia jest taka sama jak w .gitignore. Możesz używać wzorców glob:

.env*
*.local
config/*.json
.vscode/settings.json

Anthropic podaje jasną zasadę, która zapobiega wypadkom:

Innymi słowy, nie da się przypadkowo skopiować package.json przez .worktreeinclude — nie znajduje się on w .gitignore. Można bezpiecznie umieszczać tam dowolne wzorce.

Ten sam .worktreeinclude działa w trzech trybach: ręcznym --worktree, automatycznych worktree dla subagentów (patrz niżej) oraz sesjach aplikacji desktopowej Claude.

Worktree z pull requesta do przeglądu kodu#

Typowy scenariusz przeglądu kodu: kolega wysłał PR, a ty musisz sprawdzić kod, uruchomić testy i zostawić komentarz. Przy zwykłym git checkout pull/1234/head ponownie przełączasz kopię roboczą i zakłócasz aktywną sesję.

Z flagą --worktree wystarczy jedno polecenie:

claude --worktree "#1234"

Co się dzieje: Claude Code uruchamia git fetch origin pull/1234/head, tworzy worktree w .claude/worktrees/pr-1234/ i przełącza się na gałąź PR. Uruchamia się sesja. Możesz od razu poprosić: „przeczytaj diff, uruchom testy i znajdź błędy logiczne” — podczas gdy Claude pracuje, twoja główna sesja na main nadal działa.

Alternatywną składnią jest pełny adres URL pull requesta:

claude --worktree https://github.com/OWNER/REPO/pull/1234

W prawdziwym projekcie połączenie claude --worktree "#N" z własnym subagentem do przeglądu kodu daje automatyczny przegląd w minutę lub dwie. Uruchom go w tle, kontynuuj pracę w głównym oknie, a potem wróć do wyniku przez claude agents.

Gałąź bazowa: worktree.baseRef z wartością fresh lub head#

Domyślne ustawienie oznacza, że każde nowe worktree zaczyna się od origin/HEAD. Zaletą jest czysty punkt startowy, który na pewno odpowiada temu, co zobaczy CI. Wadą jest to, że niezatwierdzone zmiany ani lokalne commity wykraczające poza stan zdalny nie zostaną uwzględnione w nowym worktree.

Aby worktree startowało z bieżącego lokalnego commita HEAD, dodaj wpis do .claude/settings.json lub ustawień globalnych:

{
  "worktree": {
    "baseRef": "head"
  }
}

Teraz claude --worktree experimental-feature startuje z bieżącego lokalnego HEAD. To przydatne, gdy funkcja ma już lokalne niewysłane commity. Nie obejmuje niezacommitowanych edycji śledzonych plików. Jeśli subagent ich potrzebuje, zachowaj i jawnie przenieś wymagane zmiany, potem obejrzyj diff celu; nie myl tego z .worktreeinclude dla ignorowanych plików lokalnych.

Ustawienie przyjmuje dokładnie dwie wartości: "fresh" (= origin/HEAD) i "head" (= lokalny HEAD). Nie przyjmuje dowolnych refs, takich jak "feature-branch" ani hash commita — to celowe ograniczenie, które zapobiega kombinatorycznej eksplozji opcji.

Automatyczna izolacja subagentów: isolation: worktree#

Gdy powiesz Claude: „uruchom trzech subagentów: pierwszy czyta bazę danych, drugi sprawdza API, a trzeci testy”, wszyscy trzej domyślnie pracują na twojej kopii roboczej. Jeśli nawet dwóch z nich zapisze jednocześnie ten sam plik, powstanie konflikt. Rozwiązaniem jest automatyczne przydzielenie każdemu własnego worktree.

Metoda 1: poproś słownie. Napisz Claude w rozmowie:

Używaj worktree dla swoich agentów.

Claude zastosuje izolację do wszystkich kolejnych subagentów uruchamianych w tej sesji.

Metoda 2: ustaw to jawnie w samym subagencie. W pliku subagenta (na przykład .claude/agents/code-reviewer.md) dodaj pole do frontmatter:

---
name: code-reviewer
description: Reads the diff and writes code review comments
isolation: worktree
---

Jesteś skrupulatnym recenzentem. Przeczytaj diff i poszukaj błędów logicznych...

Teraz każde uruchomienie tego subagenta otrzyma tymczasowe worktree w .claude/worktrees/. Jeśli subagent niczego nie zmienił, folder zostanie automatycznie usunięty po zakończeniu. Jeśli pozostały niezatwierdzone zmiany, Claude zapyta, czy je zachować, czy usunąć.

Gałąź bazowa worktree subagentów jest taka sama jak dla --worktree: domyślnie origin/HEAD, a przy worktree.baseRef: head — lokalny HEAD.

Matryca decyzji: worktree, /bg, subagent czy Agent View#

Typowe kombinacje:

• „Ręcznie, równolegle dwie funkcje” — dwa terminale, w każdym claude --worktree. Najprostszy przypadek.
• „Uruchom refaktoryzację na noc, zamknę aplikację” — /bg + /goal z warunkiem ukończenia. Sesja działa niezależnie od twojego okna.
• „Jeden prompt, trzy równoległe analizy” — trzech subagentów z isolation: worktree. Każdy pracuje we własnej piaskownicy.
• „Co teraz działa?” — claude agents. Panel wszystkich sesji z filtrami „działa”, „zablokowana” i „gotowa”.

5 pułapek podczas pracy z worktree#

1. Uruchomiono worktree, brakuje .env i nic nie działa. To najczęstszy problem. Worktree to świeże pobranie bez plików ignorowanych przez Git. Rozwiązaniem jest dodanie pliku .worktreeinclude z .env* i niezbędnymi lokalnymi konfiguracjami zaraz po skonfigurowaniu trybu worktree. Sprawdź, czy plik znajduje się w katalogu głównym repozytorium, a nie w .claude/.

2. Chcesz przełączyć się na gałąź main, wykonujesz cd do katalogu głównego i tracisz niezatwierdzone zmiany w worktree. Folder główny i worktree to dwie różne kopie robocze. Po powrocie za pomocą cd zmiany w worktree nadal tam są — nigdzie nie zniknęły. Jeśli jednak pomylisz miejsca i wykonasz git stash w głównym folderze, myśląc, że jesteś w worktree, stash zostanie utworzony na gałęzi głównej, a nie na tej, której się spodziewasz.

3. Uruchomiono 5 równoległych sesji i nie pamiętasz, co robi każda z nich. Dokumentacja Anthropic wyraźnie ostrzega, że większość programistów nie jest w stanie poznawczo obsłużyć więcej niż 2–3 sesji. Oznaką przeciążenia jest otwarcie Agent View i niemożność natychmiastowego powiedzenia, czym zajmuje się każdy agent. Ogranicz się do dwóch jednoczesnych sesji. Jeśli zadanie wymaga ich więcej, należy koordynować je przez /goal + subagentów, a nie ręcznie.

4. Worktree uruchomione przez -p (tryb bez interakcji) nie są automatycznie czyszczone. Polecenie claude --worktree feature-x -p "do thing" nie wyświetla interaktywnego monitu przy wyjściu, więc nie ma momentu, w którym Claude pyta „usunąć worktree?”. Takie worktree się gromadzą. Czyść je ręcznie: git worktree remove .claude/worktrees/feature-x. Możesz też użyć skryptu cron, który usuwa elementy starsze niż 7 dni.

5. Okno dialogowe zaufania w nowym folderze. Jeśli po raz pierwszy otworzysz repozytorium i od razu uruchomisz claude --worktree, polecenie zakończy się niepowodzeniem. Uruchom claude bez flag, zaakceptuj zaufanie do obszaru roboczego i zakończ — wtedy --worktree zadziała. To celowe zabezpieczenie, dzięki któremu Claude nie uzyska dostępu do cudzego projektu bez zgody użytkownika.

Czyszczenie: co jest usuwane automatycznie#

Logika czyszczenia zależy od tego, co zrobiłeś w worktree i jak uruchomiłeś sesję. Dokumentacja Anthropic wymienia trzy scenariusze:

Scenariusz 1: wchodzisz, nic nie robisz i wychodzisz — worktree zostaje usunięte.

Scenariusz 2: wykonujesz pracę, ale jej nie commitujesz — przy wyjściu Claude zapyta „zachować czy usunąć?”. „Zachowaj” zapisuje folder i gałąź do późniejszego użycia. „Usuń” kasuje katalog razem z niezatwierdzonymi zmianami i nowymi commitami. To działanie destrukcyjne — nie klikaj „usuń” z przyzwyczajenia.

Scenariusz 3: uruchamiasz polecenie z -p (tryb bez interakcji), a następnie kończy ono działanie. Worktree pozostaje. Wyczyść je ręcznie:

git worktree remove .claude/worktrees/feature-x

Ponadto worktree z subagentów i sesji /bg są automatycznie usuwane przez czyszczenie w tle, jeśli są starsze niż cleanupPeriodDays dni (ustawienie, zwykle domyślnie 30 dni) i nie zawierają niezapisanej pracy. Worktree utworzone przez --worktree nie podlegają automatycznemu czyszczeniu — odpowiadasz za nie samodzielnie.

Rozwiązania dla SVN, Perforce i Mercurial: hook WorktreeCreate#

Jeśli repozytorium korzysta z Subversion lub Mercurial, flaga --worktree nie zadziała bezpośrednio. Anthropic udostępnia punkt rozszerzeń za pomocą dwóch hooków: WorktreeCreate (tworzy odizolowaną kopię) i WorktreeRemove (usuwa ją).

Przykładowy hook SVN z oficjalnej dokumentacji:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

Hook odczytuje nazwę worktree ze stdin ({ "name": "feature-auth" }), wykonuje svn checkout do wcześniej wyznaczonego katalogu i wypisuje ścieżkę na stdout — Claude Code używa jej jako katalogu roboczego nowej sesji.

Ważne zastrzeżenie: przy użyciu własnego hooka .worktreeinclude nie jest stosowany. Jeśli nowy folder ma zawierać .env lub inne pliki ignorowane przez Git, skopiuj je bezpośrednio w skrypcie hooka.

Co dalej: trzy powiązane mechanizmy pracy równoległej#

Worktree zapewnia izolację plików. /bg zapewnia izolację kontekstu. Subagenci zapewniają izolację zadań. Każdy mechanizm samodzielnie rozwiązuje jeden problem. Razem umożliwiają równoległą pracę nad trzema do pięciu zadaniami bez poznawczego przeciążenia. To zestaw umiejętności stojący za zaawansowanym vibe-codingiem w 2026 roku.

Ten temat naturalnie prowadzi do trzech powiązanych zagadnień: jak skonfigurować autonomicznego agenta za pomocą /goal i Agent View, jak zbudować własnych subagentów do swoich zadań oraz jak uruchamiać setki agentów za pomocą Dynamic Workflows.

Otwórz Ailoot.