Worktrees med nav-pilot og cplt

Hvorfor worktrees

En worktree er en ekstra utsjekking av samme repo, på en annen gren og i en annen mappe. Du kan la agenten jobbe på én gren mens du selv jobber på en annen, eller la flere underagenter jobbe parallelt uten å skrive over hverandres filer. Objekter, refs og konfig ligger i én felles git-mappe, den git rev-parse --git-common-dir viser. Hver worktree har i stedet for en .git-mappe en .git-fil som peker til sin egen admin-mappe under <felles>/worktrees/<navn>.

Det er tre måter å bruke worktrees på med nav-pilot og cplt:

• Du starter nav-pilot i en worktree du har laget selv.
• Agenten lager worktrees til underagenter mens den jobber.
• Du jobber i en worktree fra et bare repo, eller med .git et annet sted.

Den første og den tredje virker uten oppsett. Den andre må du slå på, og den virker bare på macOS.

Før du starter

Worktrees til underagenter krever cplt 2026.09.24-164900-53d4462 eller nyere, på macOS. Sjekk versjonen:

cplt --version

cplt er en egen pakke. brew upgrade navikt/tap/nav-pilot oppgraderer bare nav-pilot, og nav-pilot upgrade foreslår bare å oppgradere cplt når nav-pilot også er utdatert. Oppgrader cplt selv:

brew update
brew upgrade navikt/tap/cplt

Starte i en worktree

Lag worktreen utenfor sandkassen, og start nav-pilot i den:

cd ~/src/min-app
git worktree add ../min-app-ny-gren -b ny-gren
cd ../min-app-ny-gren
nav-pilot

nav-pilot gir cplt worktreen som prosjektkatalog. cplt finner den felles git-mappa, her .git-mappa i hovedutsjekkingen, og gir agenten tilgang til den, så git status, git commit og resten virker. På macOS er hooks og config i den felles git-mappa og config.worktree for hver worktree fortsatt stengt for skriving. Agenten kan ikke skrive i selve hovedutsjekkingen, bare i worktreen.

Den felles git-mappa må ligge under hjemmekatalogen din. Ligger den et annet sted, for eksempel under /Users/Shared, gir cplt ikke tilgang, og git feiler i sandkassen.

Godkjenningen av repoets .cplt.toml gjelder hele repoet, ikke én utsjekking. Har du godkjent den i hovedutsjekkingen, spør ikke cplt på nytt i worktreen, med mindre grenen har endret forslaget.

Worktrees til underagenter

Som standard kan agenten bare skrive i prosjektkatalogen, så den har ikke noe sted å lage nye worktrees. Slå på en egen worktree-mappe for repoet:

cplt config set sandbox.allow_git_worktrees true           # alle repoer
cplt config set --local sandbox.allow_git_worktrees true   # bare denne utsjekkingen

Neste gang du starter nav-pilot, lager cplt mappa ~/.cplt-worktrees/<id>, viser den når cplt starter, og setter miljøvariabelen CPLT_WORKTREE_ROOT. Mappa hører til dette repoet. Alle worktrees av samme repo får samme mappe, mens en annen klone får sin egen.

Du trenger ikke be agenten om å bruke mappa. cplt forteller agenten om den i starten av økten, sammen med kommandoen den skal bruke:

git worktree add "$CPLT_WORKTREE_ROOT/<navn>" -b <gren>

Worktrees og grener agenten lager, blir liggende etter økten. Rydd opp selv, utenfor cplt:

git worktree list
git worktree remove ~/.cplt-worktrees/<id>/<navn>
git branch -d <gren>

Innstillingen kan bare settes i din egen cplt-konfig. Et repo kan ikke slå den på for deg med .cplt.toml.

Bare repo og .git et annet sted

Noen holder repoet som et bare repo, uten arbeidskatalog, og har hver gren som en worktree ved siden av. Andre har git-mappa et annet sted enn koden. Begge deler virker på samme måte som når du starter i en worktree: cplt følger .git-fila til den felles git-mappa og gir agenten tilgang dit.

git clone --bare git@github.com:navikt/min-app.git ~/src/min-app.git
git -C ~/src/min-app.git worktree add ~/src/min-app-main main
cd ~/src/min-app-main
nav-pilot

Det samme kravet gjelder: den felles git-mappa må ligge under hjemmekatalogen din. cplt godtar bare oppsett slik git selv lager dem, så en .git-fil som er endret for hånd til å peke på et annet repo, gir ingen tilgang.

Bruker du worktrees til underagenter i tillegg, kan ikke repoet bruke worktree.useRelativePaths. cplt nekter å starte når en worktree i repoet har relative stier, også worktrees utenfor worktree-mappa. Slå av innstillingen, og skriv om stiene i worktreene som allerede finnes. Kjør det utenfor cplt, med stien til hver worktree som har relative stier:

git config --unset worktree.useRelativePaths
git worktree repair --no-relative-paths ~/src/min-app-main

Begrensninger og sikkerhet

• Ingen isolasjon mellom underagenter. Alle worktrees i en økt deler samme tilgang. En underagent kan skrive i de andres worktrees og i utsjekkingen du startet fra. Worktrees holder parallelt arbeid fra hverandre, men beskytter det ikke mot en annen agent.
• Bare macOS. På Linux nekter cplt config set å slå på worktrees til underagenter, fordi Landlock ikke kan stenge filer inne i mappa. De to andre måtene virker på Linux også.
• Samme beskyttelse som i prosjektet. Hooks og config i den felles git-mappa, config.worktree for hver worktree, .cplt.toml, .github/hooks og de andre beskyttede filene er stengt for skriving i hver worktree.
• cplt sjekker mappa ved hver oppstart og ved slutten av økten. Finner den en .git eller et bare repo der git ikke selv ville lagt det, eller en symlenke som peker ut av worktreen, nekter den å starte og sier hvilke mapper du ikke skal kjøre git i.
• Endringsrapporten dekker ikke worktrees. Rapporten cplt skriver etter økten, viser bare endringer i prosjektkatalogen. Se over det agenten har gjort i worktreene, før du kjører noe derfra utenfor sandkassen.

Detaljene står i konfigurasjonsdokumentasjonen til cplt og i SECURITY.md (engelsk).

Feilsøking

unknown config key 'sandbox.allow_git_worktrees'

cplt er for gammel. Oppgrader med brew update og brew upgrade navikt/tap/cplt, og sjekk at cplt --version viser 2026.09.24-164900-53d4462 eller nyere.

git feiler i sandkassen, men virker utenfor

Den felles git-mappa (git rev-parse --git-common-dir) ligger utenfor hjemmekatalogen, eller stien har et tegn cplt ikke kan bruke: anførselstegn, parentes, semikolon eller omvendt skråstrek. Da får ikke agenten tilgang til den. cplt sier fra ved oppstart når det er tegnene som er problemet, men ikke når mappa ligger utenfor hjemmekatalogen. Flytt repoet inn under hjemmekatalogen, eller gi mappa et navn uten de tegnene.

cplt vil ikke starte etter git worktree remove

git worktree remove feiler inne i sandkassen og etterlater en halvveis slettet worktree. Slett mappa og rydd opp utenfor cplt:

rm -rf ~/.cplt-worktrees/<id>/<navn>
git worktree prune

cplt sier at worktree-mappa har for mange mapper

Sjekken går gjennom høyst 100 000 mapper. Noen få store JavaScript-worktrees kan være nok. Slett worktrees du er ferdig med, eller hev grensen:

cplt config set sandbox.worktree_walk_max_dirs 300000

Go-bygg feiler med exit status 128 i en worktree

Go leter oppover etter en .git-mappe for å stemple bygget med versjonsinformasjon. I en worktree er .git en fil, så Go går forbi den og kan finne en annen .git-mappe høyere opp, for eksempel i hjemmekatalogen din hvis den er et git-repo. Den har ikke agenten tilgang til, og bygget feiler med error obtaining VCS status: exit status 128. Slå av stemplingen:

go build -buildvcs=false

Bygger du gjennom mise, kan du sette det for hele repoet i mise.toml:

[env]
GOFLAGS = "-buildvcs=false"

GOFLAGS satt i skallet ditt hjelper ikke, fordi cplt ikke sender variabelen inn i sandkassen. Se cplt-sak 617.

Andre problemer med cplt står i feilsøkingsguiden.