Git worktree v Claude Code: paralelní relace

Praktické informace o práci s Ailoot najdete v dokumentaci.

Co je git worktree v Claude Code?#

Spouštění několika agentů paralelně ve stejné složce je základní problém vibe-codingu v tempu roku 2026. AI agenti píšou kód rychleji, než člověk stíhá sledovat, kdo pracuje na čem. Bez izolace souborů skončí spuštění dvou paralelních relací Claude Code v jednom adresáři tak, že jedna přepíše práci druhé.

Git worktree to řeší na úrovni souborového systému. Máte jeden hlavní adresář, ve kterém pracujete. Příkaz claude --worktree feature-auth vytvoří složku .claude/worktrees/feature-auth/ na samostatné větvi a spustí v ní Claude Code. Soubory jsou izolované. Změny v jedné relaci nejsou viditelné v druhé, dokud je výslovně nesloučíte.

Oficiální dokumentace Anthropic to popisuje takto:

Nápověda k sebekontrole: pokud jste někdy dostali commit, ve kterém polovinu souborů vytvořil někdo jiný, potřebujete worktree.

Jak se git worktree liší od běžné větve?#

Standardní postup v Gitu: jste na větvi main a spustíte git checkout feature-x — Git přepíše soubory pracovní kopie. Běžící npm run dev přestane fungovat, protože se mu pod rukama změnil package.json. Uložíte necommitované změny pomocí git stash a čekáte, až IDE znovu zindexuje soubory. Přepnete se zpět a všechno se znovu přepíše, takže musíte znovu provést stash a pop.

Git worktree nabízí jinou možnost: místo přepínání jedné složky mezi větvemi vytvoříte druhou složku pro další větev. Příkaz git worktree add ../project-feature-x feature-x vytvoří adresář ../project-feature-x/ se soubory z větve feature-x. Větev main zůstane v původní složce a vývojový server běží dál.

Dříve bylo nutné režim worktree v Claude Code nastavovat ručně: git worktree add, potom cd a pak claude — a to opakovat v každém terminálu. Příznak --worktree (také -w) zvládne všechny tři kroky jedním příkazem.

Spuštění první paralelní relace: příznak --worktree#

Minimální příklad. Otevřete první terminál v kořenovém adresáři projektu:

claude --worktree feature-auth

Claude Code provede tři kroky:

1. Vytvoří .claude/worktrees/feature-auth/ se snímkem stavu origin/HEAD (obvykle vaší výchozí větve).
2. Vytvoří novou větev worktree-feature-auth.
3. Spustí relaci v této složce.

Otevřete druhý terminál ve stejné kořenové složce repozitáře:

claude --worktree bugfix-123

Hotovo. Dvě relace Claude Code, různé soubory na disku a různé větve Gitu. Pokud v první napíšete autentizaci a ve druhé opravíte neprocházející test, fyzicky si nemohou překážet.

Pokud nechcete zadávat název, Claude ho vymyslí:

claude --worktree
# → vytvoří něco jako .claude/worktrees/bright-running-fox/

Tip pro začátečníky s Gitem: přidejte .claude/worktrees/ do .gitignore. Jinak při spuštění git status v hlavní složce uvidíte obsah všech worktree jako nesledované soubory:

# .gitignore
.claude/worktrees/

Čemu se vyhnout: před prvním spuštěním --worktree v novém adresáři do něj nejprve vstupte běžným příkazem claude (bez příznaku) a přijměte dialog důvěry v pracovní prostor. Pokud to neuděláte, příznak selže s chybou „trust not accepted“ — včetně případu, kdy ho zkombinujete s -p pro bezhlavý režim.

Kde worktree najdete a jak je zobrazit#

Výchozí umístění je pevně dané: .claude/worktrees/<value>/ v kořenovém adresáři repozitáře. Pokud máte projekt v ~/dev/my-app/, worktree feature-auth bude v ~/dev/my-app/.claude/worktrees/feature-auth/.

Pro nestandardní uspořádání (například chcete-li worktree mimo repozitář) existuje hook WorktreeCreate — více o něm níže v části o SVN a Mercurial.

V rámci jedné relace Claude můžete přepnout do jiného existujícího worktree. Stačí do chatu napsat: „přejdi do .claude/worktrees/bugfix-123“ a Claude zavolá nástroj EnterWorktree. Aktuální složka zůstane nedotčená — stejným způsobem se do ní můžete vrátit.

Standardní příkaz Gitu zobrazí seznam všech worktree včetně hlavního a těch vytvořených ručně:

git worktree list

Výstup bude vypadat 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írování .env a tajných údajů: soubor .worktreeinclude#

Když --worktree vytvoří novou složku, obsahuje pouze to, co je commitnuté v Gitu. .env s klíči API a .env.local s místní konfigurací jsou v .gitignore, takže v worktree nejsou. A hned první npm run dev skončí chybou „MISSING DATABASE_URL“.

Podomácku vytvořené řešení spočívá v ručním kopírování .env po každém spuštění --worktree. Jednou to funguje, pak se na to zapomene. Řešením Anthropic je soubor .worktreeinclude v kořenovém adresáři projektu se seznamem souborů ignorovaných Gitem, které se mají automaticky kopírovat do každého nového worktree.

Vytvořte soubor .worktreeinclude v kořenovém adresáři repozitáře:

.env
.env.local
config/secrets.json

Syntaxe je stejná jako v .gitignore. Lze použít vzory glob:

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

Anthropic uvádí jasné pravidlo, které předchází nehodám:

Jinými slovy, přes .worktreeinclude nemůžete omylem zkopírovat package.json — není v .gitignore. Je bezpečné tam uvést libovolné vzory.

Stejný .worktreeinclude funguje ve třech režimech: ruční --worktree, automatická worktree pro subagenty (viz níže) a relace z desktopové aplikace Claude.

Worktree z pull requestu pro kontrolu kódu#

Běžný scénář kontroly kódu: kolega poslal PR; potřebujete prohlédnout kód, spustit testy a zanechat komentář. Při běžném git checkout pull/1234/head znovu přepnete pracovní kopii a narušíte aktivní relaci.

S příznakem --worktree to zvládnete jedním příkazem:

claude --worktree "#1234"

Co se stane: Claude Code spustí git fetch origin pull/1234/head, vytvoří worktree v .claude/worktrees/pr-1234/ a přepne se na větev PR. Spustí se relace. Můžete hned požádat, aby „přečetl diff, spustil testy a našel logické chyby“ — zatímco Claude pracuje, vaše hlavní relace na main běží dál.

Alternativní zápis je úplná URL pull requestu:

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

Použití ve skutečném projektu: když spojíte claude --worktree "#N" s vlastním subagentem pro kontrolu kódu, získáte automatickou kontrolu během minuty nebo dvou. Spusťte ho na pozadí, pokračujte v práci v hlavním okně a k výsledku se vraťte přes claude agents.

Výchozí větev: worktree.baseRef pro fresh nebo head#

Výchozí nastavení je následující: každé nové worktree začíná z origin/HEAD. Výhodou je čistý začátek, který se zaručeně shoduje s tím, co uvidí CI. Nevýhodou je, že se do nového worktree nezahrnou necommitované změny ani několik místních commitů navíc oproti vzdálené větvi.

Chcete-li worktree spustit z aktuálního místního commitu HEAD, přidejte toto do .claude/settings.json (nebo globální konfigurace):

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

Nyní claude --worktree experimental-feature začíná z aktuálního místního HEAD. Hodí se to pro funkci s místními commity, které ještě nejsou odeslané. Nezahrnuje to stále necommitnuté úpravy sledovaných souborů. Potřebuje-li je podagent, zachovejte a výslovně přeneste požadované změny a ověřte cílový diff; tento přenos nezaměňujte s .worktreeinclude pro ignorované místní soubory.

Toto nastavení přijímá přesně dvě hodnoty: "fresh" (= origin/HEAD) a "head" (= místní HEAD). Libovolné refy jako "feature-branch" nebo hash commitu podporované nejsou — jde o záměrné omezení, které má zabránit kombinatorické explozi možností.

Automatická izolace subagentů: isolation: worktree#

Když Claude řeknete „spusť tři subagenty: jeden prohlédne databázi, druhý se podívá na API a třetí zkontroluje testy“, všichni tři ve výchozím nastavení pracují ve vaší pracovní kopii. Pokud třeba jen dva z nich současně upravují stejný soubor, dojde ke konfliktu. Řešením je automaticky každému přidělit vlastní worktree.

Metoda 1: požádejte ho běžným způsobem. Napište Claudeovi v konverzaci:

Use worktrees for your agents.

Claude použije izolaci pro všechny následující subagenty v této relaci.

Metoda 2: nastavte ji přímo v definici subagenta. Do souboru subagenta (například .claude/agents/code-reviewer.md) přidejte pole do záhlaví:

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

You're a meticulous reviewer. Read the diff and look for logic errors...

Od této chvíle dostane každé spuštění tohoto subagenta dočasné worktree v .claude/worktrees/. Pokud subagent nic nezapsal, složka se po jeho dokončení automaticky odstraní. Pokud jsou v něm necommitované změny, Claude se zeptá, zda je ponechat, nebo odstranit.

Výchozí větev pro worktree subagentů je stejná jako pro --worktree: standardně origin/HEAD, s worktree.baseRef: head místní HEAD.

Rozhodovací matice: worktree, /bg, subagent nebo Agent View#

Typické kombinace:

• „2 funkce paralelně, ručně“ — dva terminály, v každém běží claude --worktree. Nejjednodušší případ.
• „Spusť noční refaktoring; zavřu aplikaci“ — /bg + /goal s podmínkou dokončení. Relace běží nezávisle na vašem okně.
• „Jedno zadání, tři paralelní průzkumy“ — tři subagenti s isolation: worktree. Každý ve vlastním izolovaném prostředí.
• „Co právě běží?“ — claude agents. Ovládací panel všech relací s filtry „běží“, „blokováno“ a „hotovo“.

5 úskalí při práci s worktree#

1. Spustili jste worktree, chybí .env a nic nefunguje. Nejčastější problém. Worktree je čistá kopie repozitáře bez souborů ignorovaných Gitem. Při nastavování režimu worktree přidejte co nejdříve soubor .worktreeinclude se vzorem .env* a potřebnými místními konfiguracemi. Zkontrolujte, že soubor leží v kořenovém adresáři repozitáře, ne v .claude/.

2. Chcete přepnout na hlavní větev, zadáte cd do kořenového adresáře a přijdete o necommitované změny ve worktree. Kořenová složka a worktree jsou dvě různé pracovní kopie. Vrátili jste se příkazem cd; změny ve worktree zůstaly na místě — nikam nezmizely. Pokud jste se ale spletli a spustili git stash v hlavní složce v domnění, že jste ve worktree, stash se vytvoří na hlavní větvi, ne na té očekávané.

3. Spustili jste 5 paralelních relací a už si nepamatujete, co každá dělá. Dokumentace Anthropic výslovně upozorňuje, že většina vývojářů nedokáže kognitivně zvládnout více než 2–3 relace. Přetížení poznáte podle toho, že otevřete Agent View a nedokážete hned říct, co který agent dělá. Omezte se na dvě souběžné relace. Pokud úkol vyžaduje více, měli byste práci řídit přes /goal + subagenty, ne ručně.

4. Worktree spuštěná s -p (bezhlavý režim) se automaticky neuklidí. Příkaz claude --worktree feature-x -p "do thing" nezobrazí interaktivní výzvu při ukončení, takže nenastane okamžik, kdy se Claude zeptá „odstranit worktree?“. Tato worktree se hromadí. Ukliďte je ručně: git worktree remove .claude/worktrees/feature-x. Nebo použijte cron skript, který odstraní vše starší než 7 dní.

5. Dialog důvěry v nové složce. Pokud repozitář otevíráte poprvé a hned spustíte claude --worktree, příkaz selže. Spusťte claude bez příznaků, přijměte důvěru v pracovní prostor a ukončete relaci — pak už --worktree bude fungovat. Je to záměrné opatření, aby Claude nezískal přístup k cizímu projektu bez souhlasu uživatele.

Úklid: co se odstraní automaticky#

Logika úklidu závisí na tom, co jste ve worktree udělali a jak jste relaci spustili. Dokumentace Anthropic uvádí tři scénáře:

Scénář 1: vstoupili jste, nic neudělali a odešli — worktree bylo odstraněno.

Scénář 2: něco jste udělali, ale necommitovali jste to — při ukončení se Claude zeptá „ponechat, nebo odstranit?“. Volba „ponechat“ uloží složku a větev pro pozdější použití. Volba „odstranit“ smaže adresář spolu s necommitovanými změnami a novými commity. Je to nevratné — neklikejte na „odstranit“ ze zvyku.

Scénář 3: spustili jste relaci s -p (bezhlavý režim) a příkaz skončil. Worktree zůstane. Ukliďte je ručně:

git worktree remove .claude/worktrees/feature-x

Worktree od subagentů a z relací /bg navíc automaticky odstraňuje úklid na pozadí, pokud jsou starší než cleanupPeriodDays dní (nastavení, obvykle ve výchozím stavu 30 dní) a zároveň neobsahují neuloženou práci. Worktree z --worktree automatický úklid nezasáhne — za jejich úklid odpovídáte vy.

Alternativy pro SVN, Perforce a Mercurial: hook WorktreeCreate#

Pokud repozitář používá Subversion nebo Mercurial, příznak --worktree nebude fungovat přímo. Anthropic nabízí rozšiřující bod prostřednictvím dvou hooků: WorktreeCreate (vytvoří izolovanou kopii) a WorktreeRemove (odstraní ji).

Příklad hooku SVN z oficiální dokumentace:

{
  "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 čte název worktree ze stdin ({ "name": "feature-auth" }), spouští svn checkout do předem určeného adresáře a vypíše cestu na stdout — Claude Code ji použije jako pracovní adresář nové relace.

Důležité upozornění: při použití vlastního hooku se .worktreeinclude nepoužije. Pokud v nové složce potřebujete .env nebo jiné soubory ignorované Gitem, zkopírujte je přímo v samotném skriptu hooku.

Co dál: tři související mechanismy paralelní práce#

Worktree poskytuje izolaci souborů. /bg poskytuje izolaci kontextu. Subagenti poskytují izolaci úkolů. Každý mechanismus samostatně řeší jeden problém. Společně umožňují pracovat na třech až pěti paralelních úkolech bez kognitivního přetížení. To jsou dovednosti, na kterých stojí pokročilý vibe-coding v roce 2026.

Téma přirozeně navazuje na tři související oblasti: jak nastavit autonomního agenta pomocí /goal a Agent View, jak si vytvořit vlastní subagenty pro své úkoly a jak spouštět stovky agentů pomocí Dynamic Workflows.

Přejděte na Ailoot.