Git worktree Claude Codessa: rinnakkaiset istunnot

Käytännön tietoa Ailootin käytöstä on dokumentaatiossa.

Mikä on git worktree Claude Codessa#

Useiden agenttien käynnistäminen rinnakkain samassa kansiossa on vibe-koodauksen perusongelma vuoden 2026 tahdissa. Tekoälyagentit kirjoittavat koodia nopeammin kuin ihminen ehtii seurata, kuka käsittelee mitäkin. Ilman tiedostojen eristämistä kaksi rinnakkain samassa hakemistossa käynnistettyä Claude Code -istuntoa päätyy siihen, että toinen istunto kirjoittaa toisen työn päälle.

Git worktree ratkaisee ongelman tiedostojärjestelmän tasolla. Sinulla on yksi päähakemisto, jossa työskentelet. Komento claude --worktree feature-auth luo kansion .claude/worktrees/feature-auth/ erilliselle haaralle ja käynnistää Claude Coden siellä. Tiedostot on eristetty. Toisen istunnon muutokset eivät näy toisessa ennen kuin yhdistät ne nimenomaisesti.

Anthropicin virallisessa dokumentaatiossa asia ilmaistaan näin:

Vinkki itsearviointiin: jos olet joskus saanut commitin, jossa puolet tiedostoista oli jonkun muun työtä, tarvitset worktreen.

Miten git worktree eroaa tavallisesta haarasta#

Tavallinen Git-työnkulku: olet main-haarassa ja suoritat git checkout feature-x—Git korvaa työkopion tiedostot. Käynnissä oleva npm run dev hajoaa, koska package.json muuttui sen alta. Talletat commitoimattomat muutokset stashilla ja odotat, että IDE indeksoi tiedostot uudelleen. Vaihdat takaisin, ja kaikki korvataan taas, joten joudut tekemään uudestaan stashin ja popin.

Git worktree tarjoaa toisen vaihtoehdon: sen sijaan, että vaihtaisit yhtä kansiota haarojen välillä, luot toisen kansion toiselle haaralle. Komento git worktree add ../project-feature-x feature-x luo hakemiston ../project-feature-x/, jossa ovat feature-x-haaran tiedostot. main jää alkuperäiseen kansioon, ja kehityspalvelin jatkaa toimintaansa.

Aiemmin Claude Coden worktree-tila piti ottaa käyttöön manuaalisesti: git worktree add, sitten cd, sitten claude—ja sama piti toistaa jokaisessa päätteessä. --worktree-valitsin (myös -w) hoitaa kaikki kolme yhdellä komennolla.

Käynnistä ensimmäinen rinnakkainen istunto: --worktree-valitsin#

Yksinkertainen esimerkki. Avaa ensimmäinen pääte projektin juuressa:

claude --worktree feature-auth

Claude Code tekee kolme asiaa:

1. Luo hakemiston .claude/worktrees/feature-auth/, jossa on tilannevedos origin/HEAD-haarasta (yleensä oletushaarastasi).
2. Luo uuden worktree-feature-auth-haaran.
3. Käynnistää istunnon tässä kansiossa.

Avaa toinen pääte saman repositoryn juurikansiossa:

claude --worktree bugfix-123

Valmista. Kaksi Claude Code -istuntoa, eri tiedostot levyllä, eri Git-haarat. Jos kirjoitat autentikoinnin ensimmäisessä ja korjaat epäonnistuvan testin toisessa, ne eivät fyysisesti voi häiritä toisiaan.

Jos et halua kirjoittaa nimeä, Claude keksii sellaisen:

claude --worktree
# → luo esimerkiksi hakemiston .claude/worktrees/bright-running-fox/

Vinkki Gitin aloittelijoille: lisää .claude/worktrees/ tiedostoon .gitignore. Muuten git status näyttää päähakemistossa kaikkien worktreeiden sisällön seuraamattomina tiedostoina:

# .gitignore
.claude/worktrees/

Vältä tätä sudenkuoppaa: ennen ensimmäistä --worktree-käynnistystä uudessa hakemistossa avaa se tavallisella claude-komennolla (ilman valitsinta) ja hyväksy työtilan luottamusdialogi. Jos et tee näin, valitsin epäonnistuu virheeseen “trust not accepted”—myös silloin, kun yhdistät sen headless-tilan -p-valitsimeen.

Missä worktreet sijaitsevat ja miten löydät ne#

Oletussijainti on kiinteä: .claude/worktrees/<value>/ repositoryn juuressa. Jos projektisi on hakemistossa ~/dev/my-app/, feature-auth-worktree sijaitsee hakemistossa ~/dev/my-app/.claude/worktrees/feature-auth/.

Epätyypillisiin rakenteisiin (esimerkiksi jos haluat worktreen repositoryn ulkopuolelle) on WorktreeCreate-hook, josta kerrotaan lisää alla SVN:ää ja Mercurialia käsittelevässä osiossa.

Yhden Claude-istunnon sisällä voit siirtyä toiseen olemassa olevaan worktreeen. Sano keskustelussa: “siirry hakemistoon .claude/worktrees/bugfix-123”, niin Claude kutsuu EnterWorktree-työkalua. Nykyinen kansio pysyy koskemattomana—voit palata samalla tavalla.

Tavallinen Git-komento näyttää kaikki worktreet, myös päätyökopion ja manuaalisesti luodut worktreet:

git worktree list

Tuloste näyttää tältä:

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

Kopioi .env ja salaisuudet: .worktreeinclude-tiedosto#

Kun --worktree luo uuden kansion, se saa vain Git-repositoryyn commitatut tiedostot. API-avaimia sisältävä .env ja paikalliset asetukset sisältävä .env.local ovat .gitignore-tiedostossa, joten niitä ei ole worktreessä. Ensimmäinen npm run dev epäonnistuu virheeseen “MISSING DATABASE_URL”.

Itse tehty ratkaisu on kopioida .env manuaalisesti jokaisen --worktree-komennon jälkeen. Se toimii kerran ja unohtuu sitten. Anthropicin ratkaisu on projektin juuressa oleva .worktreeinclude-tiedosto, jossa luetellaan Gitin ohittamat tiedostot, jotka kopioidaan automaattisesti jokaiseen uuteen worktreeen.

Luo .worktreeinclude-tiedosto repositoryn juuressa:

.env
.env.local
config/secrets.json

Syntaksi on sama kuin .gitignore-tiedostossa. Voit käyttää glob-kuvioita:

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

Anthropic antaa selkeän säännön vahinkojen välttämiseksi:

Toisin sanoen .worktreeinclude-tiedostolla ei voi vahingossa kopioida package.json-tiedostoa—se ei ole .gitignore-tiedostossa. Tiedostoon voi turvallisesti lisätä mitä tahansa kuvioita.

Sama .worktreeinclude toimii kolmessa tilassa: manuaalisessa --worktree-käytössä, aliagenttien automaattisissa worktreeissä (katso alla) ja Claude-työpöytäsovelluksesta käynnistetyissä istunnoissa.

Worktree pull requestista koodikatselmointia varten#

Tavallinen koodikatselmoinnin tilanne: kollega lähetti PR:n; sinun täytyy tarkastaa koodi, suorittaa testit ja jättää kommentti. Tavallisella git checkout pull/1234/head -komennolla vaihdat työkopion taas ja keskeytät aktiivisen istuntosi.

--worktree-valitsimella tämä hoituu yhdellä komennolla:

claude --worktree "#1234"

Näin tapahtuu: Claude Code suorittaa komennon git fetch origin pull/1234/head, luo worktreen hakemistoon .claude/worktrees/pr-1234/ ja ottaa PR-haaran käyttöön. Istunto käynnistyy. Voit heti pyytää sitä “lukemaan diffin, suorittamaan testit ja etsimään loogisia virheitä”—Claude työskentelee, kun taas pääistuntosi haarassa main jatkaa toimintaansa.

Vaihtoehtoinen syntaksi on koko pull request -URL-osoite:

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

Oikeassa projektissa voit yhdistää claude --worktree "#N" -komennon omaan koodikatselmointi-aliagenttiin ja saada automaattisen katselmoinnin parissa minuutissa. Käynnistä se taustalla, jatka työskentelyä pääikkunassa ja palaa tulokseen komennolla claude agents.

Perushaara: worktree.baseRef arvolla fresh tai head#

Oletusarvo on, että jokainen uusi worktree aloittaa lähteestä origin/HEAD. Etuna on puhdas lähtökohta, joka vastaa varmasti sitä, mitä CI näkee. Haittana on se, etteivät commitoimattomat muutokset tai useat paikalliset commitit nykyisellä haarallasi etävaraston version jälkeen sisälly uuteen worktreeen.

Jos haluat aloittaa worktreen nykyisestä paikallisesta HEAD-commitista, lisää tämä tiedostoon .claude/settings.json (tai globaaleihin asetuksiin):

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

Nyt claude --worktree experimental-feature aloittaa nykyisestä paikallisesta HEAD-commitista. Tästä on hyötyä, kun ominaisuudestasi on jo paikallisia committeja, joita ei ole pushattu. Committoimattomat seurattujen tiedostojen muokkaukset eivät sisälly mukaan. Jos aliagentti tarvitsee niitä, säilytä ja siirrä tarvittavat muutokset erikseen ja tarkista kohteen diffi. Älä sekoita siirtoa .worktreeinclude-tiedostoon, joka käsittelee Gitin ohittamia paikallisia tiedostoja.

Asetus hyväksyy täsmälleen kaksi arvoa: "fresh" (= origin/HEAD) ja "head" (= paikallinen HEAD). Mielivaltaisia ref-arvoja, kuten "feature-branch" tai commit-hashia, ei voi antaa—tämä on tarkoituksellinen rajoitus vaihtoehtojen yhdistelmien räjähdysmäisen kasvun estämiseksi.

Eristä aliagentit automaattisesti: isolation: worktree#

Kun pyydät Claudea “käynnistämään kolme aliagenttia: yksi lukee tietokantaa, toinen tarkastelee APIa ja kolmas tarkistaa testit”, kaikki kolme työskentelevät oletusarvoisesti työkopiossasi. Jos edes kaksi niistä kirjoittaa samaan tiedostoon yhtä aikaa, syntyy ristiriita. Ratkaisuna on antaa kullekin oma worktree automaattisesti.

Menetelmä 1: pyydä sanallisesti. Kirjoita Claude-keskusteluun:

Käytä agenteillesi worktree-työpuita.

Claude ottaa eristyksen käyttöön kaikille tämän istunnon myöhemmille aliagenteille.

Menetelmä 2: määritä se nimenomaisesti aliagentin määrityksessä. Lisää kenttä aliagentin tiedoston frontmatter-osiolle (esimerkiksi .claude/agents/code-reviewer.md):

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

Olet huolellinen tarkastaja. Lue diff ja etsi logiikkavirheitä...

Nyt jokainen tämän aliagentin käynnistys saa väliaikaisen worktreen hakemistoon .claude/worktrees/. Jos aliagentti ei kirjoittanut mitään, kansio poistetaan automaattisesti sen valmistuttua. Jos muutoksia ei ole commitoitu, Claude kysyy, säilytetäänkö vai poistetaanko ne.

Aliagenttien worktreeiden perushaara on sama kuin --worktree-valitsimessa: oletusarvoisesti origin/HEAD; kun worktree.baseRef: head, paikallinen HEAD.

Päätösmatriisi: worktree, /bg, aliagentti vai Agent View#

Tyypillisiä yhdistelmiä:

• “2 ominaisuutta rinnakkain, manuaalisesti” — kaksi päätettä, joissa kummassakin suoritetaan claude --worktree. Yksinkertaisin tapaus.
• “Käynnistä refaktorointi yöksi; suljen sovelluksen” — /bg + /goal ja valmistumisehto. Istunto toimii ikkunastasi riippumatta.
• “Yksi prompt, kolme rinnakkaista tutkimusta” — kolme aliagenttia asetuksella isolation: worktree. Jokainen omassa hiekkalaatikossaan.
• “Mitä on käynnissä juuri nyt?” — claude agents. Kaikkien istuntojen hallintapaneeli, jossa on suodattimet “running”, “blocked” ja “done”.

5 worktreeiden käytön sudenkuoppaa#

1. Käynnistit worktreen, .env puuttuu eikä mikään toimi. Yleisin ongelma. Worktree on tuore checkout, josta puuttuvat kaikki Gitin ohittamat tiedostot. Ratkaisuna on lisätä .worktreeinclude-tiedosto, jossa on .env* ja tarvittavat paikalliset asetukset, heti kun otat worktree-tilan käyttöön. Tarkista, että tiedosto on repositoryn juuressa eikä hakemistossa .claude/.

2. Haluat vaihtaa main-haaraan, suoritat cd-komennon juuressa olevaan kansioon ja menetät worktreessä olevat commitointia odottavat muutokset. Juurikansio ja worktree ovat kaksi eri työkopiota. Palasit komennolla cd; worktreen muutokset pysyivät paikallaan—ne eivät kadonneet minnekään. Mutta jos menit sekaisin ja suoritit git stash -komennon päähakemistossa luullen olevasi worktreessä, stash luodaan main-haaraan eikä odottamaasi haaraan.

3. Käynnistit 5 rinnakkaista istuntoa etkä muista, mitä kukin tekee. Anthropicin dokumentaatio varoittaa nimenomaisesti, että useimmat kehittäjät eivät pysty hallitsemaan mielessään yli 2–3 istuntoa. Ylikuormituksen merkki on se, että avaat Agent Viewin etkä pysty heti sanomaan, mitä kukin agentti tekee. Rajoita samanaikaiset istunnot kahteen. Jos tehtävä edellyttää useampia, ne kannattaa orkestroida /goal-komennolla ja aliagenteilla, ei manuaalisesti.

4. -p-valitsimella (headless) luotuja worktreitä ei siivota automaattisesti. Komento claude --worktree feature-x -p "do thing" ei näytä vuorovaikutteista poistumiskehotetta, joten Claude ei missään vaiheessa kysy “poistetaanko worktree?”. Näitä worktreitä kertyy. Siivoa ne manuaalisesti: git worktree remove .claude/worktrees/feature-x. Tai käytä cron-skriptiä, joka poistaa kaiken yli 7 päivää vanhan.

5. Luottamusdialogi uudessa kansiossa. Jos avaat repositoryn ensimmäistä kertaa ja suoritat heti claude --worktree, komento epäonnistuu. Suorita claude ilman valitsimia, hyväksy työtilan luottamus ja poistu—sen jälkeen --worktree toimii. Tämä on tarkoituksellista, jotta Claude ei pääse toisen henkilön projektiin ilman käyttäjän suostumusta.

Siivoaminen: mitä poistetaan automaattisesti#

Siivouslogiikka riippuu siitä, mitä olet tehnyt worktreessä ja miten käynnistit istunnon. Anthropicin dokumentaatiossa luetellaan kolme tilannetta:

Tilanne 1: siirryit sisään, et tehnyt mitään ja poistuit—worktree poistettiin.

Tilanne 2: teit hieman työtä mutta et commitoitu sitä—Claude kysyy poistuessasi “säilytetäänkö vai poistetaanko?”. “Säilytä” tallentaa kansion ja haaran myöhempää käyttöä varten. “Poista” poistaa hakemiston yhdessä commitointia odottavien muutosten ja uusien commitien kanssa. Tämä on tuhoavaa—älä napsauta “poista” tottumuksesta.

Tilanne 3: käynnistit komennon -p-valitsimella (headless), ja komento päättyi. Worktree jää paikalleen. Siivoa se manuaalisesti:

git worktree remove .claude/worktrees/feature-x

Lisäksi aliagenttien ja /bg-istuntojen worktreet poistetaan automaattisesti taustasiivouksessa, jos ne ovat vanhempia kuin cleanupPeriodDays päivää (asetus on tavallisesti oletusarvoisesti 30 päivää) ja niissä ei ole tallentamatonta työtä. --worktree-komennolla luotuihin worktreihin automaattinen siivous ei koske—ne ovat sinun vastuullasi.

Vaihtoehdot SVN:lle, Perforcelle ja Mercurialille: WorktreeCreate-hook#

Jos repository käyttää Subversionia tai Mercurialia, --worktree-valitsin ei toimi suoraan. Anthropic tarjoaa laajennuskohdan kahden hookin kautta: WorktreeCreate (luo eristetyn kopion) ja WorktreeRemove (poistaa sen).

Esimerkki SVN-hookista virallisesta dokumentaatiosta:

{
  "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 lukee worktreen nimen stdin-syötteestä ({ "name": "feature-auth" }), suorittaa svn checkout -komennon ennalta määritettyyn hakemistoon ja tulostaa polun stdoutiin—Claude Code käyttää sitä uuden istunnon työhakemistona.

Tärkeä huomautus: omaa hookia käytettäessä .worktreeinclude ei ole käytössä. Jos tarvitset uuteen kansioon .env-tiedoston tai muita Gitin ohittamia tiedostoja, kopioi ne itse hook-skriptiä käyttäen.

Seuraavaksi: kolme rinnakkaisen työskentelyn lähimekanismia#

Worktree eristää tiedostot. /bg eristää kontekstin. Aliagentit eristävät tehtävät. Kukin mekanismi ratkaisee yhden ongelman erikseen. Yhdessä ne mahdollistavat työskentelyn kolmen tai viiden rinnakkaisen tehtävän parissa ilman kognitiivista romahdusta. Tämä on vuonna 2026 edistyneen vibe-koodauksen työkalupakki.

Aihe jatkuu luontevasti kolmella läheisellä aiheella: näin määrität autonomisen agentin /goal-komennolla ja Agent Viewillä, näin rakennat omia aliagentteja tehtäviisi ja näin käynnistät satoja agentteja Dynamic Workflows -toiminnolla.

Avaa Ailoot.