Git worktree a Claude Code-ban: párhuzamos munkamenetek

Az Ailoot használatával kapcsolatos gyakorlati információkat a dokumentációban találod.

Mi az a git worktree a Claude Code-ban?#

Több ügynök párhuzamos indítása ugyanabban a mappában a vibe-coding alapvető fájdalompontja 2026-os sebességnél. Az AI-ügynökök gyorsabban írnak kódot, mint ahogy az ember követni tudná, ki min dolgozik. Fájl-elkülönítés nélkül két párhuzamos Claude Code-munkamenet ugyanabban a könyvtárban történő elindítása oda vezet, hogy az egyik munkamenet felülírja a másik munkáját.

A Git worktree fájlrendszerszinten oldja meg ezt. Van egy fő könyvtárad, ahol dolgozol. A claude --worktree feature-auth parancs létrehozza a .claude/worktrees/feature-auth/ mappát egy külön ágon, és ott indítja el a Claude Code-ot. A fájlok elkülönülnek. Az egyik munkamenet módosításai nem láthatók a másikban, amíg kifejezetten össze nem fésülöd őket.

Az Anthropic hivatalos dokumentációja így fogalmaz:

Önellenőrzési tipp: ha kaptál már olyan commitot, amelynek fájljai közül az egyik fele valaki más munkája volt, worktree-re van szükséged.

Miben különbözik a git worktree a hagyományos ágtól?#

A szokásos Git-munkafolyamat: a main ágon vagy, és futtatod a git checkout feature-x parancsot—a Git felülírja a munkapéldány fájljait. A futó npm run dev leáll, mert közben megváltozott a package.json. Elmented a nem commitolt módosításaidat a stash-be, és megvárod, amíg az IDE újraindexel. Visszaváltasz, minden megint felülíródik, ezért ismét stash-elned és pop-olnod kell.

A Git worktree másik lehetőséget kínál: ahelyett, hogy egyetlen mappát váltogatnál az ágak között, létrehozol egy második mappát egy másik ágnak. A git worktree add ../project-feature-x feature-x parancs létrehozza a ../project-feature-x/ könyvtárat a feature-x ág fájljaival. A main az eredeti mappában marad, a fejlesztői szerver pedig tovább fut.

Korábban a Claude Code worktree-módját kézzel kellett beállítani: git worktree add, majd cd, aztán claude—és ezt minden terminálban megismételni. A --worktree flag (vagy -w) mindhárom lépést elvégzi egyetlen paranccsal.

Az első párhuzamos munkamenet indítása: a --worktree flag#

Minimális példa. Nyisd meg az első terminált a projekt gyökérkönyvtárában:

claude --worktree feature-auth

A Claude Code három dolgot végez el:

1. Létrehozza a .claude/worktrees/feature-auth/ mappát az origin/HEAD pillanatképével (általában az alapértelmezett ágaddal).
2. Létrehoz egy új worktree-feature-auth ágat.
3. Elindítja a munkamenetet ebben a mappában.

Nyiss meg egy második terminált ugyanabban a tároló gyökérkönyvtárában:

claude --worktree bugfix-123

Kész. Két Claude Code-munkamenet, különböző fájlok a lemezen, különböző Git-ágak. Ha az elsőben hitelesítést írsz, a másodikban pedig kijavítasz egy hibás tesztet, fizikailag nem tudnak egymás útjába kerülni.

Ha nem akarsz nevet beírni, a Claude kitalál egyet:

claude --worktree
# → creates something like .claude/worktrees/bright-running-fox/

Tipp a Git kezdőinek: add hozzá a .claude/worktrees/ útvonalat a .gitignore fájlhoz. Máskülönben, amikor a fő mappában futtatod a git status parancsot, az összes worktree tartalma nem követett fájlként fog megjelenni:

# .gitignore
.claude/worktrees/

Kerülendő buktató: új könyvtárban az első --worktree indítása előtt lépj be oda egy normál claude paranccsal (flag nélkül), és fogadd el a munkaterület megbízhatóságáról szóló párbeszédablakot. Ha ezt nem teszed meg, a flag „trust not accepted” hibával meghiúsul—akkor is, ha a fej nélküli módhoz használt -p flaggel kombinálod.

Hol találhatók a worktree-k, és hogyan kereshetők meg?#

Az alapértelmezett hely kötött: .claude/worktrees/<value>/ a tároló gyökérkönyvtárában. Ha a projekted a ~/dev/my-app/ útvonalon van, a feature-auth worktree itt lesz: ~/dev/my-app/.claude/worktrees/feature-auth/.

Nem szabványos elrendezéseknél (például ha a tárolón kívül szeretnéd elhelyezni a worktree-t) használható a WorktreeCreate hook—erről lentebb, az SVN-ről és Mercurialról szóló részben lesz szó.

Egy Claude-munkameneten belül átválthatsz egy másik, már létező worktree-re. Egyszerűen írd be a csevegésbe: „válts át a .claude/worktrees/bugfix-123 útvonalra”, és Claude meghívja az EnterWorktree eszközt. Az aktuális mappa érintetlen marad—ugyanígy vissza is térhetsz.

A szabványos Git-parancs az összes worktree listáját megjeleníti, a fővel és a kézzel létrehozottakkal együtt:

git worktree list

A kimenet így néz ki:

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

.env és titkok másolása: a .worktreeinclude fájl#

Amikor a --worktree új mappát hoz létre, csak a Gitbe commitolt fájlok kerülnek bele. Az API-kulcsokat tartalmazó .env és a helyi beállításokat tartalmazó .env.local a .gitignore fájlban szerepel, ezért nincsenek a worktree-ben. Emiatt az első npm run dev azonnal „MISSING DATABASE_URL” hibával leáll.

A házi megoldás az, hogy minden --worktree után kézzel másolod át a .env fájlt. Egyszer működik, aztán elfelejted. Az Anthropic megoldása egy .worktreeinclude fájl a projekt gyökerében, amely felsorolja a Git által figyelmen kívül hagyott fájlokat, és automatikusan átmásolja őket minden új worktree-be.

Hozz létre egy .worktreeinclude fájlt a tároló gyökérkönyvtárában:

.env
.env.local
config/secrets.json

A szintaxis megegyezik a .gitignore fájl szintaxisával. Globmintákat is használhatsz:

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

Az Anthropic egyértelmű szabályt ad a balesetek elkerülésére:

Más szóval a .worktreeinclude segítségével nem másolhatod át véletlenül a package.json fájlt, mert az nincs a .gitignore fájlban. Bármilyen mintát biztonságosan elhelyezhetsz benne.

Ugyanaz a .worktreeinclude három módban működik: kézi --worktree, alügynökök automatikus worktree-jei (lásd lentebb) és a Claude asztali alkalmazásából indított munkamenetek.

Worktree létrehozása pull requestből kódellenőrzéshez#

Gyakori kódellenőrzési helyzet: egy kolléga küldött egy PR-t; meg kell vizsgálnod a kódot, teszteket kell futtatnod, és megjegyzést kell hagynod. A hagyományos git checkout pull/1234/head paranccsal ismét átváltod a munkapéldányt, és megszakítod az aktív munkamenetet.

A --worktree flaggel ez egyetlen parancs:

claude --worktree "#1234"

Mi történik: a Claude Code futtatja a git fetch origin pull/1234/head parancsot, létrehoz egy worktree-t a .claude/worktrees/pr-1234/ útvonalon, és checkoutolja a PR ágát. Elindul a munkamenet. Rögtön megkérheted, hogy „olvassa el a diffet, futtassa a teszteket, és keressen logikai hibákat”—miközben Claude dolgozik, a main ágon futó fő munkameneted folytatódik.

Alternatív szintaxis a teljes pull request URL:

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

Valós projektben a claude --worktree "#N" parancs és a saját kódellenőrző alügynököd párosítása egy-két perc alatt automatikus ellenőrzést ad. Indítsd el a háttérben, folytasd a munkát a főablakban, majd térj vissza az eredményhez a claude agents paranccsal.

Alapág: worktree.baseRef a fresh vagy head értékhez#

Az alapértelmezett beállítás a következő: minden új worktree az origin/HEAD alapján indul. Ennek előnye a tiszta kiindulópont, amely garantáltan megegyezik azzal, amit a CI látni fog. Hátránya, hogy ha vannak nem commitolt módosításaid, vagy több helyi commitod van a távoli ág fölött az aktuális ágon, ezek nem kerülnek bele az új worktree-be.

Az aktuális helyi HEAD commitból induláshoz add ezt a .claude/settings.json fájlhoz vagy globális beállításokhoz:

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

Most a claude --worktree experimental-feature az aktuális helyi HEAD commitból indul. Akkor hasznos, ha a funkcióhoz már vannak még nem pusholt helyi commitok. A nem commitolt követett szerkesztéseket nem veszi át. Ha az alügynöknek ezek kellenek, őrizd meg és kifejezetten vidd át a szükséges változásokat, majd nézd át a cél diffjét; ezt ne keverd a kizárt helyi fájlokat kezelő .worktreeinclude működésével.

A beállítás pontosan két értéket fogad el: "fresh" (= origin/HEAD) és "head" (= helyi HEAD). Tetszőleges ref, például "feature-branch" vagy egy commit hash nem használható—ez szándékos korlátozás, hogy ne robbanjon meg a lehetőségek kombinációinak száma.

Alügynökök automatikus elkülönítése: isolation: worktree#

Ha azt mondod Claude-nak, hogy „indíts három alügynököt: az egyik olvassa el az adatbázist, a másik vizsgálja meg az API-t, a harmadik pedig ellenőrizze a teszteket”, alapértelmezés szerint mindhárman a munkapéldányodban dolgoznak. Ha akár csak ketten egyszerre írnak ugyanabba a fájlba, konfliktus keletkezik. A megoldás az, hogy mindegyik automatikusan saját worktree-t kap.

1. módszer: kérd szóban. Írd Claude-nak a beszélgetésben:

Használj worktree-ket az ügynökeidhez.

Claude a munkamenet további alügynökeinél is alkalmazni fogja az elkülönítést.

2. módszer: állítsd be kifejezetten magánál az alügynöknél. Az alügynök fájljában (például .claude/agents/code-reviewer.md) adj hozzá egy mezőt a frontmatterhez:

---
name: code-reviewer
description: Elolvassa a diffet és kódellenőrzési megjegyzéseket ír
isolation: worktree
---

Aprólékos bíráló vagy. Olvasd el a diffet, és keresd a logikai hibákat...

Az alügynök minden indításakor ideiglenes worktree-t kap a .claude/worktrees/ útvonalon. Ha nem írt semmit, a mappa automatikusan törlődik, amikor befejezi. Ha vannak nem commitolt módosítások, Claude megkérdezi, hogy megtartsa vagy törölje-e őket.

Az alügynök-worktree-k alapága megegyezik a --worktree esetén használt ággal: alapértelmezés szerint origin/HEAD, worktree.baseRef: head esetén pedig a helyi HEAD.

Döntési mátrix: worktree, /bg, alügynök vagy Agent View#

Gyakori kombinációk:

• „2 funkció párhuzamosan, kézzel” — két terminál, mindkettőben claude --worktree. A legegyszerűbb eset.
• „Indíts egy éjszakai refaktorálást; bezárom az alkalmazást” — /bg + /goal befejezési feltétellel. A munkamenet az ablakodtól függetlenül fut.
• „Egy prompt, három párhuzamos vizsgálat” — három isolation: worktree beállítású alügynök. Mindegyik saját sandboxban.
• „Mi fut éppen?” — claude agents. Az összes munkamenet irányítópultja „running”, „blocked” és „done” szűrőkkel.

5 buktató a worktree-k használatakor#

1. Elindítottál egy worktree-t, hiányzik a .env, semmi sem működik. Ez a leggyakoribb probléma. A worktree friss checkout, Git által figyelmen kívül hagyott fájlok nélkül. A megoldás az, hogy a worktree-mód beállításakor rögtön létrehozol egy .worktreeinclude fájlt .env* mintával és a szükséges helyi konfigurációkkal. Ellenőrizd, hogy a fájl a tároló gyökerében van-e, nem a .claude/ mappában.

2. A fő ágra szeretnél váltani, a gyökérhez futtatod a cd parancsot, és elvesznek a worktree nem commitolt módosításai. A gyökérmappa és a worktree két különböző munkapéldány. A cd paranccsal visszatértél; a worktree változásai a helyükön maradtak—nem tűntek el. De ha összekeverted a helyeket, és a fő mappában futtattad a git stash parancsot, mert azt hitted, hogy a worktree-ben vagy, a stash a fő ágon jön létre, nem azon, amelyiken vártad.

3. Elindítottál 5 párhuzamos munkamenetet, és már nem emlékszel, melyik mit csinál. Az Anthropic dokumentációja kifejezetten figyelmeztet arra, hogy a legtöbb fejlesztő kognitív szempontból nem tud 2–3 munkamenetnél többet kezelni. A túlterheltség jele, ha megnyitod az Agent View-t, és nem tudod azonnal megmondani, melyik ügynök mit csinál. Korlátozd magad két egyidejű munkamenetre. Ha a feladat ennél többet igényel, /goal + alügynökök segítségével kell koordinálni, nem kézzel.

4. A -p flaggel (fej nélküli módban) indított worktree-k nem tisztulnak meg automatikusan. A claude --worktree feature-x -p "do thing" parancs nem jelenít meg interaktív kilépési kérdést, ezért nincs olyan pont, amikor Claude megkérdezné: „eltávolítsam a worktree-t?” Ezek a worktree-k felhalmozódnak. Takarítsd ki őket kézzel: git worktree remove .claude/worktrees/feature-x. Vagy használj cron-szkriptet, amely mindent eltávolít, ami 7 napnál régebbi.

5. Bizalmi párbeszédablak új mappában. Ha először nyitod meg a tárolót, és rögtön futtatod a claude --worktree parancsot, a parancs meghiúsul. Futtasd a claude parancsot flag nélkül, fogadd el a munkaterület megbízhatóságát, majd lépj ki—ezután a --worktree működni fog. Ez szándékos, így Claude nem férhet hozzá más projektjéhez a felhasználó beleegyezése nélkül.

Takarítás: mi törlődik automatikusan?#

A takarítási logika attól függ, mit csináltál a worktree-ben, és hogyan indítottad el a munkamenetet. Az Anthropic dokumentációja három forgatókönyvet sorol fel:

1. forgatókönyv: beléptél, nem csináltál semmit, majd kiléptél—a worktree törlődött.

2. forgatókönyv: dolgoztál rajta, de nem commitoltál—kilépéskor Claude megkérdezi: „megtartod vagy törlöd?” A „megtartás” elmenti a mappát és az ágat későbbre. Az „eltávolítás” törli a könyvtárat az összes nem commitolt módosítással és új commitokkal együtt. Ez visszafordíthatatlan művelet—ne kattints megszokásból az „eltávolításra”.

3. forgatókönyv: a -p flaggel indítottad el (fej nélküli módban), a parancs pedig befejeződött és kilépett. A worktree megmarad. Takarítsd ki kézzel:

git worktree remove .claude/worktrees/feature-x

Emellett az alügynökök és a /bg munkamenetek worktree-jeit a háttérben futó takarítás automatikusan eltávolítja, ha a cleanupPeriodDays értékénél több naposak (ez egy beállítás, alapértelmezés szerint általában 30 nap) és nincs bennük el nem mentett munka. A --worktree worktree-ket az automatikus takarítás nem érinti—ezek kezelése a te felelősséged.

Alternatívák SVN-hez, Perforce-hoz és Mercurialhoz: a WorktreeCreate hook#

Ha a tároló Subversiont vagy Mercurialt használ, a --worktree flag közvetlenül nem fog működni. Az Anthropic két hookkal biztosít bővítési pontot: a WorktreeCreate (elkülönített másolat létrehozása) és a WorktreeRemove (eltávolítása).

Példa SVN-hook a hivatalos dokumentációból:

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

A hook stdin-ről olvassa be a worktree nevét ({ "name": "feature-auth" }), lefuttatja a svn checkout parancsot egy előre meghatározott könyvtárba, majd kiírja az útvonalat stdout-ra—a Claude Code ezt használja az új munkamenet munkakönyvtáraként.

Fontos megjegyzés: saját hook használatakor a .worktreeinclude nem érvényesül. Ha szükséged van a .env fájlra vagy más, Git által figyelmen kívül hagyott fájlokra az új mappában, másold át őket magában a hook-szkriptben.

Mi következik: három kapcsolódó párhuzamossági mechanizmus#

A worktree fájl-elkülönítést ad. A /bg kontextus-elkülönítést biztosít. Az alügynökök feladat-elkülönítést nyújtanak. Mindegyik mechanizmus önmagában egy problémát old meg. Együttesen módot adnak három-öt párhuzamos feladat elvégzésére kognitív összeomlás nélkül. Ez a 2026-os haladó vibe-coding mögött álló készségkészlet.

A téma természetes folytatása három kapcsolódó terület: autonóm ügynök beállítása a /goal és az Agent View használatával, saját alügynökök készítése a feladataidhoz, valamint ügynökök százainak indítása Dynamic Workflows segítségével.

Ailoot megnyitása.