Nativní podporu funkce Git Worktrees představil Anthropic do Claude Code teprve v únoru. Ale pokud pracujete na projektu s kolegy, měli byste věnovat pozornost jejímu správnému použití. Takže, jak na paralelní vývoj?
Samotná funkce Git worktrees není také nijak nová – git worktree je součástí Gitu od verze 2.5 (2015). Pokud s ním pracujete poprvé, základní princip: jeden repozitář může mít více pracovních adresářů (worktrees), každý s vlastním HEAD a checkout větví. Sdílejí společnou Git databázi objektů, takže nedochází k duplikaci historie ani blobů.
Claude Code od verze 2.1.50 tuto funkcionalitu nativně integruje přes příznak --worktree. Přidaná hodnota oproti ruční správě git worktree je minimální, ale ne nulová: Claude automaticky pojmenuje a umístí worktree, spustí novou session s kontextem přiřazeným k dané větvi a zajistí, že subagenti mohou pracovat izolovaně bez sdílení souborového stavu.
Paralelní práce na nezávislých funkcích, kde agenti nesdílí soubory. Pokud mají vaše features vzájemné závislosti nebo zasahují do stejných modulů, worktrees problém merge konfliktů pouze odloží – nevyřeší.
K čemu tedy worktree slouží? A kdy ji máte použít?
Worktree má smysl tehdy, když potřebuješ pracovat na více nezávislých úkolech současně, aniž by se navzájem blokovaly. Typický příklad: opravuješ produkční chybu v jedné větvi, zatímco v druhé pokračuje vývoj nové funkce. Nebo vyvíjíš dvě funkce najednou a chceš je nasazovat v jiný čas. Bez worktree bys musel přerušit práci, uložit rozdělaný stav přes git stash nebo dočasný commit, přepnout větev a po návratu celý kontext obnovit. A to je trochu opruz.
Podobně užitečné je to při code review: místo přepínání větve a narušení aktuálního stavu si otevřeš recenzovanou větev v samostatném worktree a procházíš ji nezávisle. Worktree tedy není nástroj pro každodenní práci na jednom úkolu — jeho hodnota roste s počtem současně aktivních kontextů, které potřebuješ udržet izolované. A samozřejmě také tehdy, když na různých úkolech pracuje více lidí.
Prerekvizity
- Claude Code ≥ 2.1.50 (ověření:
claude update) - Inicializovaný Git repozitář s alespoň jedním commitem na hlavní větvi
git log --oneline # musí vrátit alespoň jeden záznam
Worktrees nefungují v repozitářích bez prvního commitu.
Základní použití
Spuštění session v novém worktree
claude --worktree feature/dark-mode
Claude vytvoří nový worktree na větvi feature/dark-mode a spustí session s pracovním adresářem nastaveným na tento worktree. Pokud větev neexistuje, Claude ji vytvoří.
Worktree je uložen pod:
.claude/worktrees/feature-dark-mode/
Hlavní větev zůstane nedotčena.
Zkrácený příznak
claude -w feature/dark-mode
Ověření aktivních worktrees
git worktree list
Výstup ukáže cestu, HEAD commit a název větve pro každý aktivní worktree.
Navigace a práce s worktrees
Přímý přechod do adresáře worktree
cd .claude/worktrees/feature-dark-mode
Nebo spuštění session přímo v tomto adresáři:
claude --worktree feature/dark-mode --dir
Obnovení přerušené session
Pokud session ukončíte a chcete ji obnovit, spusťte stejný příkaz znovu:
claude --worktree feature/dark-mode
Claude načte existující worktree a pokračuje ve stejném kontextu.
Přepínání mezi sessions
Uvnitř Claude Code: Ctrl+W zobrazí seznam všech aktivních sessions v projektu a umožní přepínání.
Úklid
Worktrees je potřeba explicitně odstraňovat. Bez úklidu se hromadí pod .claude/worktrees/.
# Standardní odstranění
git worktree remove .claude/worktrees/feature-dark-mode
# Vynucené odstranění (worktree obsahuje necommitované změny)
git worktree remove --force .claude/worktrees/feature-dark-mode
# Úklid odkazů na již odstraněné worktrees
git worktree prune
Doporučený postup: odstraňte worktree ihned po mergi odpovídající větve.
Paralelní subagenti
Worktrees lze využít i pro spouštění více subagentů souběžně z jedné hlavní session. Instrukce Claudovi:
Use worktrees for your agents. Build feature/dark-mode, feature/local-storage,
and feature/edit-todos in parallel — each in its own branch. Make sure each
agent tests its changes end to end before opening a PR.
Claude spustí tři subagenty, každého v samostatném worktree. Výsledky lze reviewovat a mergovat nezávisle.
Pozor na náklady: Paralelní agenti znamenají paralelní spotřebu tokenů. U komplexnějších úkolů náklady rostou lineárně s počtem agentů.
Automatická izolace pro vlastní agenty
Pokud máte v projektu definované vlastní agenty (.claude/agents/), lze jim nastavit automatickou worktree izolaci v jejich frontmatter:
---
name: feature-builder
model: claude-sonnet-4-6
isolation: worktree
---
You are a feature development specialist. When assigned a feature,
build it completely, write tests, and verify it works before finishing.
Always work in small, focused commits.
Každé spuštění tohoto agenta pak automaticky dostane vlastní worktree bez potřeby ručního přidávání příznaků.
Integrace s desktopovou aplikací
Claude Desktop (záložka Code) nabízí grafický checkbox pro aktivaci worktree módu před spuštěním session. Funkcionalita je identická s CLI verzí.
Omezení a reálná očekávání
Co worktrees řeší:
- Izolace souborového systému mezi agenty – jeden agent nemůže přepsat soubor, na kterém pracuje jiný.
- Eliminace potřeby ručního
git stash/ přepínání větví při přechodu mezi úkoly. - Možnost reviewovat nebo mergovat hotové features bez čekání na dokončení ostatních.
Co worktrees neřeší:
- Merge konflikty při integraci větví zpět do main. Pokud dvě features mění stejné soubory (i na různých místech), konflikt nastane při mergi bez ohledu na worktrees.
- Koordinaci závislostí mezi agenty. Pokud feature B závisí na výstupu feature A, izolace nepomůže – musíte řídit pořadí ručně.
- Sdílený stav (databáze, konfigurační soubory, environment proměnné). Izolace je výhradně na úrovni souborového systému.
Vhodné případy použití:
- Nezávislé features bez sdílených souborů
- Oprava produkčního bugu paralelně s vývojem nové funkce
- Code review v izolovaném prostředí bez narušení aktuálního stavu
Nevhodné případy použití:
- Úkoly s vzájemnými závislostmi (doporučte sekvenční zpracování)
- Malé projekty s jedním vývojářem a jednou aktivní funkcí – overhead není odůvodněný
- Repozitáře s komplexními build systémy, kde každý worktree potřebuje vlastní
node_modulesnebo jiné velké závislosti (diskový prostor)
Shrnutí příkazů
| Operace | Příkaz |
|---|---|
| Nový worktree + session | claude --worktree feature/nazev |
| Totéž, zkráceně | claude -w feature/nazev |
| Spustit přímo v adresáři worktree | claude -w feature/nazev --dir |
| Obnovit session | claude -w feature/nazev (stejný příkaz) |
| Přehled aktivních worktrees | git worktree list |
| Přepínání sessions | Ctrl+W uvnitř Claude Code |
| Odstranění worktree | git worktree remove .claude/worktrees/feature-nazev |
| Vynucené odstranění | git worktree remove --force .claude/worktrees/feature-nazev |
| Úklid odkazů | git worktree prune |