Git worktree v Claude Code: paralelné relácie

Praktické informácie o práci s Ailoot nájdete v dokumentácii.

Čo je git worktree v Claude Code#

Spúšťanie viacerých agentov paralelne v rovnakom priečinku je základný problém vibe-codingu pri rýchlosti roku 2026. AI agenti píšu kód rýchlejšie, než človek stíha sledovať, kto práve mení ktoré súbory. Bez izolácie súborov sa spustenie dvoch paralelných relácií Claude Code v jednom adresári skončí tým, že jedna relácia prepíše prácu druhej.

Git worktree rieši tento problém na úrovni súborového systému. Máte jeden hlavný adresár, v ktorom pracujete. Príkaz claude --worktree feature-auth vytvorí priečinok .claude/worktrees/feature-auth/ na samostatnej vetve a spustí v ňom Claude Code. Súbory sú izolované. Zmeny v jednej relácii nie sú viditeľné v druhej, kým ich výslovne nezlúčite.

Oficiálna dokumentácia Anthropic to opisuje takto:

Pomôcka na sebaoverenie: ak ste niekedy dostali commit, v ktorom polovica súborov pochádzala od niekoho iného, potrebujete worktree.

Ako sa git worktree líši od bežnej vetvy#

Štandardný postup v Gite: ste na vetve main a spustíte git checkout feature-x—Git prepíše súbory pracovnej kópie. Spustený proces npm run dev prestane fungovať, pretože sa pod ním zmenil package.json. Odložíte nepotvrdené zmeny a čakáte, kým IDE znova zaindexuje súbory. Prepnete sa späť a všetko sa opäť prepíše, takže musíte znovu vykonať stash a pop.

Git worktree ponúka ďalšiu možnosť: namiesto prepínania jedného priečinka medzi vetvami vytvoríte pre inú vetvu druhý priečinok. Príkaz git worktree add ../project-feature-x feature-x vytvorí adresár ../project-feature-x/ so súbormi z vetvy feature-x. Vaša vetva main zostane v pôvodnom priečinku a vývojový server beží ďalej.

Predtým bolo potrebné režim worktree v Claude Code nastaviť ručne: git worktree add, potom cd a následne claude—a to zopakovať v každom termináli. Prepínač --worktree (tiež -w) vykoná všetky tri kroky jediným príkazom.

Spustenie prvej paralelnej relácie: prepínač --worktree#

Minimálny príklad. Otvorte prvý terminál v koreňovom adresári projektu:

claude --worktree feature-auth

Claude Code vykoná tri veci:

1. Vytvorí .claude/worktrees/feature-auth/ so snímkou origin/HEAD (zvyčajne vašej predvolenej vetvy).
2. Vytvorí novú vetvu worktree-feature-auth.
3. Spustí reláciu v tomto priečinku.

Otvorte druhý terminál v rovnakom koreňovom priečinku repozitára:

claude --worktree bugfix-123

Hotovo. Dve relácie Claude Code, rôzne súbory na disku, rôzne vetvy Gitu. Ak v prvej píšete kód na autentifikáciu a v druhej opravujete zlyhávajúci test, fyzicky si nemôžu navzájom prekážať.

Ak nechcete zadávať názov, Claude nejaký vymyslí:

claude --worktree
# → vytvorí napríklad .claude/worktrees/bright-running-fox/

Tip pre začiatočníkov v Gite: pridajte .claude/worktrees/ do .gitignore. Inak pri spustení git status v hlavnom priečinku uvidíte obsah všetkých worktrees ako nesledované súbory:

# .gitignore
.claude/worktrees/

Pozor na jednu pascu: pred prvým spustením --worktree v novom adresári doň vstúpte bežným príkazom claude (bez prepínača) a prijmite dialóg dôveryhodnosti pracovného priestoru. Ak to neurobíte, prepínač zlyhá s chybou „trust not accepted“—aj keď ho skombinujete s -p pre bezhlavý režim.

Kde sa worktrees nachádzajú a ako ich nájsť#

Predvolené umiestnenie je pevne dané: .claude/worktrees/<value>/ v koreňovom adresári repozitára. Ak sa váš projekt nachádza v ~/dev/my-app/, worktree feature-auth bude v ~/dev/my-app/.claude/worktrees/feature-auth/.

Pre neštandardné rozloženia (napríklad ak chcete worktree umiestniť mimo repozitára) existuje hook WorktreeCreate—viac sa o ňom dočítate nižšie v časti o SVN a Mercuriale.

V rámci jednej relácie Claude môžete prejsť do iného existujúceho worktree. Stačí v chate povedať: „switch to .claude/worktrees/bugfix-123“ a Claude zavolá nástroj EnterWorktree. Aktuálny priečinok zostane nedotknutý—rovnakým spôsobom sa doň môžete vrátiť.

Štandardný príkaz Gitu zobrazí zoznam všetkých worktrees vrátane hlavného a tých, ktoré boli vytvorené ručne:

git worktree list

Výstup bude vyzerať takto:

/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]

Kopírovanie .env a tajných údajov: súbor .worktreeinclude#

Keď --worktree vytvorí nový priečinok, obsahuje iba to, čo je commitnuté v Gite. Súbory .env s kľúčmi API a .env.local s miestnou konfiguráciou sú v .gitignore, takže v worktree nie sú. A hneď prvé npm run dev zlyhá s hlásením „MISSING DATABASE_URL“.

Domáce riešenie spočíva v ručnom kopírovaní .env po každom --worktree. Raz to funguje, potom na to zabudnete. Riešením Anthropic je súbor .worktreeinclude v koreňovom adresári projektu, ktorý uvádza súbory ignorované Gitom, ktoré sa majú automaticky kopírovať do každého nového worktree.

Vytvorte súbor .worktreeinclude v koreňovom adresári repozitára:

.env
.env.local
config/secrets.json

Syntax je rovnaká ako v .gitignore. Môžete použiť vzory glob:

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

Anthropic uvádza jasné pravidlo, ktoré predchádza nehodám:

Inými slovami, cez .worktreeinclude nemôžete omylom skopírovať package.json—nie je v .gitignore. Je bezpečné uviesť tam ľubovoľné vzory.

Ten istý .worktreeinclude funguje v troch režimoch: pri ručnom --worktree, automatických worktrees pre subagentov (pozrite nižšie) a reláciách z počítačovej aplikácie Claude.

Worktree z pull requestu na kontrolu kódu#

Typický scenár kontroly kódu: kolega poslal PR; musíte skontrolovať kód, spustiť testy a zanechať komentár. Pri bežnom git checkout pull/1234/head znova prepnete pracovnú kópiu a narušíte aktívnu reláciu.

S prepínačom --worktree to zvládnete jediným príkazom:

claude --worktree "#1234"

Čo sa stane: Claude Code spustí git fetch origin pull/1234/head, vytvorí worktree v .claude/worktrees/pr-1234/ a checkoutne vetvu PR. Relácia sa spustí. Môžete ho hneď požiadať, aby „prečítal diff, spustil testy a našiel logické chyby“—zatiaľ čo Claude pracuje, vaša hlavná relácia na main beží ďalej.

Alternatívnou syntaxou je úplná URL pull requestu:

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

Použitie v skutočnom projekte: spojenie claude --worktree "#N" s vlastným subagentom na kontrolu kódu vám poskytne automatickú kontrolu za minútu či dve. Spustite ho na pozadí, pokračujte v práci v hlavnom okne a k výsledku sa vráťte cez claude agents.

Základná vetva: worktree.baseRef pre fresh alebo head#

Predvolené nastavenie je takéto: každý nový worktree začína z origin/HEAD. Výhodou je čistý začiatok, ktorý sa zaručene zhoduje s tým, čo uvidí CI. Nevýhodou je, že ak máte na aktuálnej vetve nepotvrdené zmeny alebo niekoľko miestnych commitov navyše oproti vzdialenej vetve, v novom worktree nebudú zahrnuté.

Na vytvorenie worktree z aktuálneho lokálneho HEAD commitu pridajte toto do .claude/settings.json alebo globálnych nastavení:

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

Teraz claude --worktree experimental-feature začína z aktuálneho lokálneho HEAD. Hodí sa pre funkciu s miestnymi commitmi, ktoré ešte neboli odoslané. Nezahŕňa sledované necommitnuté úpravy. Ak ich subagent potrebuje, uchovajte a preneste potrebné zmeny výslovne a prezrite cieľový diff; nemýľte si to s .worktreeinclude pre ignorované lokálne súbory.

Nastavenie prijíma presne dve hodnoty: "fresh" (= origin/HEAD) a "head" (= miestny HEAD). Ľubovoľné referencie, napríklad "feature-branch" alebo hash commitu, nie sú povolené—ide o zámerné obmedzenie, ktoré má zabrániť kombinatorickému nárastu možností.

Automatická izolácia subagentov: isolation: worktree#

Keď Claudeovi poviete „spusti troch subagentov: jeden číta databázu, druhý sa pozrie na API a tretí skontroluje testy“, všetci traja predvolene pracujú vo vašej pracovnej kópii. Ak čo i len dvaja z nich zapisujú súčasne do toho istého súboru, vznikne konflikt. Riešením je automaticky každému prideliť vlastný worktree.

Metóda 1: požiadajte ústne. Napíšte Claudeovi v konverzácii:

Použi worktrees pre svojich agentov.

Claude použije izoláciu pre všetkých nasledujúcich subagentov v tejto relácii.

Metóda 2: nastavte to výslovne v samotnom subagentovi. Do súboru subagenta (napríklad .claude/agents/code-reviewer.md) pridajte pole do frontmatteru:

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

Si dôkladný recenzent. Prečítaj diff a hľadaj logické chyby...

Každé spustenie tohto subagenta teraz získa dočasný worktree v .claude/worktrees/. Ak subagent nič nezapísal, priečinok sa po jeho skončení automaticky odstráni. Ak existujú nepotvrdené zmeny, Claude sa opýta, či ich chcete ponechať alebo odstrániť.

Základná vetva worktrees subagentov je rovnaká ako pri --worktree: predvolene origin/HEAD; pri nastavení worktree.baseRef: head miestne HEAD.

Rozhodovacia tabuľka: worktree, /bg, subagent alebo Agent View#

Typické kombinácie:

• „2 funkcie súčasne, ručne“ — dva terminály, v každom beží claude --worktree. Najjednoduchší prípad.
• „Spusti nočný refaktoring; zavriem aplikáciu“ — /bg + /goal s podmienkou dokončenia. Relácia beží nezávisle od vášho okna.
• „Jeden prompt, tri paralelné skúmania“ — traja subagenti s isolation: worktree. Každý vo vlastnom izolovanom prostredí.
• „Čo práve beží?“ — claude agents. Panel všetkých relácií s filtrami „running“, „blocked“ a „done“.

5 nástrah pri práci s worktrees#

1. Spustili ste worktree, chýba .env, nič nefunguje. Najčastejší problém. Worktree je čerstvý checkout bez súborov ignorovaných Gitom. Riešením je pridať do súboru .worktreeinclude vzor .env* a potrebné miestne konfigurácie hneď po nastavení režimu worktree. Skontrolujte, či súbor leží v koreňovom adresári repozitára, nie v .claude/.

2. Chcete prejsť na hlavnú vetvu, spustíte cd do koreňového adresára a prídete o nepotvrdené zmeny vo worktree. Koreňový priečinok a worktree sú dve odlišné pracovné kópie. Vrátili ste sa príkazom cd; zmeny vo worktree zostali na svojom mieste—nikam sa nestratili. Ak ste sa však pomýlili a spustili git stash v hlavnom priečinku v domnení, že ste vo worktree, stash sa vytvorí na hlavnej vetve, nie na tej, ktorú ste očakávali.

3. Spustili ste 5 paralelných relácií a nepamätáte si, čo každá robí. Dokumentácia Anthropic výslovne upozorňuje, že väčšina vývojárov nedokáže mentálne zvládnuť viac než 2–3 relácie. Znakom preťaženia je, keď otvoríte Agent View a neviete okamžite povedať, čo ktorý agent robí. Obmedzte sa na dve súčasné relácie. Ak úloha vyžaduje viac, mali by byť riadené cez /goal + subagentov, nie manuálne.

4. Worktrees spustené pomocou -p (bezhlavý režim) sa automaticky nečistia. Príkaz claude --worktree feature-x -p "do thing" nezobrazí interaktívnu výzvu pri ukončení, takže nenastane chvíľa, keď sa Claude opýta „odstrániť worktree?“. Tieto worktrees sa hromadia. Vyčistite ich ručne: git worktree remove .claude/worktrees/feature-x. Alebo použite skript cron, ktorý odstráni všetko staršie než 7 dní.

5. Dialóg dôveryhodnosti v novom priečinku. Ak otvoríte repozitár po prvýkrát a hneď spustíte claude --worktree, príkaz zlyhá. Spustite claude bez prepínačov, potvrďte dôveryhodnosť pracovného priestoru a ukončite ho—potom bude --worktree fungovať. Je to zámerné, aby Claude nezískal prístup k projektu niekoho iného bez súhlasu používateľa.

Čistenie: čo sa odstráni automaticky#

Logika čistenia závisí od toho, čo ste vo worktree urobili a ako ste spustili reláciu. Dokumentácia Anthropic uvádza tri scenáre:

Scenár 1: vstúpili ste, nič ste neurobili a odišli—worktree sa odstránilo.

Scenár 2: pracovali ste, ale zmeny ste necommitli—pri ukončení sa Claude opýta „ponechať alebo odstrániť?“. Voľba „ponechať“ uloží priečinok a vetvu na neskôr. Voľba „odstrániť“ zmaže adresár spolu s nepotvrdenými zmenami a novými commitmi. Je to deštruktívne—neklikajte na „odstrániť“ zo zvyku.

Scenár 3: spustili ste príkaz s -p (bezhlavý režim) a ten sa dokončil a ukončil. Worktree zostane. Vyčistite ho ručne:

git worktree remove .claude/worktrees/feature-x

Worktrees subagentov a relácií /bg sa navyše automaticky odstránia pri čistení na pozadí, ak sú staršie než cleanupPeriodDays dní (nastavenie, predvolene zvyčajne 30 dní) a neobsahujú neuloženú prácu. Worktrees z --worktree sa automatickým čistením neodstraňujú—zodpovedáte za ne vy.

Alternatívy pre SVN, Perforce a Mercurial: hook WorktreeCreate#

Ak repozitár používa Subversion alebo Mercurial, prepínač --worktree nebude fungovať priamo. Anthropic poskytuje bod rozšírenia prostredníctvom dvoch hookov: WorktreeCreate (vytvorí izolovanú kópiu) a WorktreeRemove (odstráni ju).

Príklad hooku SVN z oficiálnej dokumentácie:

{
  "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 načíta názov worktree zo stdin ({ "name": "feature-auth" }), spustí svn checkout do vopred určeného adresára a vypíše cestu na stdout—Claude Code ju použije ako pracovný adresár novej relácie.

Dôležité upozornenie: pri použití vlastného hooku sa .worktreeinclude nepoužíva. Ak v novom priečinku potrebujete .env alebo iné súbory ignorované Gitom, skopírujte ich priamo v skripte hooku.

Čo ďalej: tri súvisiace mechanizmy paralelizácie#

Worktree poskytuje izoláciu súborov. /bg poskytuje izoláciu kontextu. Subagenti poskytujú izoláciu úloh. Každý mechanizmus samostatne rieši jeden problém. Spolu ponúkajú spôsob, ako pracovať na troch až piatich paralelných úlohách bez mentálneho preťaženia. Toto sú zručnosti, ktoré stoja za pokročilým vibe-codingom v roku 2026.

Táto téma prirodzene nadväzuje na tri súvisiace témy: ako nastaviť autonómneho agenta pomocou /goal a Agent View, ako vytvoriť vlastných subagentov pre svoje úlohy a ako spúšťať stovky agentov prostredníctvom Dynamic Workflows.

Otvorte Ailoot.