Izolowane zadania Codex w Git worktrees

Zadanie Codex w worktree to jedna sesja Codex uruchomiona we własnym Git worktree, więc jej edycje, instalacje i testy nie dotykają głównego checkoutu. Codex CLI 0.157.1 tworzy zarządzany worktree przez --worktree lub /worktree; git worktree add daje zamiast tego nazwaną ścieżkę i branch. W obu przypadkach zadanie jest skończone dopiero, gdy przejdzie przez bramki jakości, a commity leżą na branchu.

Poprosiłeś Codex o naprawę niestabilnego testu autoryzacji, a sam w tym samym katalogu pracowałeś nad migracją. Po dwudziestu minutach katalog roboczy zawiera oba zestawy zmian, npm install przepisał ci lockfile, a ty nie wiesz już, które edycje są twoje. Ta strona jest dla developera, który uruchamia Codex lokalnie i chce mieć każde zadanie w osobnym checkoucie, z czystym sposobem na jego weryfikację, zachowanie i wyrzucenie.

Co daje uruchamianie zadań Codex w worktrees

• Tabelę decyzyjną: worktree zarządzany (codex --worktree), jawny (git worktree add) albo aplikacja desktopowa.
• Fakty o tym, co zarządzany worktree przenosi, a czego nie, zmierzone na Codex CLI 0.157.1.
• Skrypt bootstrapu, który przygotowuje świeży worktree do pracy bez kopiowania sekretów produkcyjnych.
• Dwa prompty do skopiowania: jeden bezpiecznie startuje zadanie w worktree, drugi oddaje je gotowe do merge’a.
• Bramkę, którą uruchamiasz przed przeczytaniem jakiegokolwiek diffa, oraz kolejność sprzątania, która nigdy nie usuwa niezmergowanego commita.

Koordynacja wielu worktrees naraz (tory pracy, skrypty fan-out, kolejność merge’y) to temat strony wieloagentowe workflow w Codex. Ta strona opisuje worktree jednego zadania od utworzenia do usunięcia.

Jaki rodzaj worktree Codex wybrać?

Obsługa worktrees jest domyślnie włączona od Codex CLI 0.156.0 (funkcja worktrees ma w codex features list status stable i wartość true, 0.157.1). Sesja nadal działa w bieżącym katalogu, dopóki sam jej nie przeniesiesz. Codex 0.162.0 (2026-10-08) dodał zarządzane narzędzia worktree Gita, które tworzą i wyświetlają worktrees z zaufanych projektów (notatki do wydania OpenAI). Pomiary przenoszenia stanu w następnej sekcji wykonano na 0.157.1, a notatki do wydania nie mówią, czy to przenoszenie się zmieniło, więc po aktualizacji powtórz tę kontrolę.

Chcesz	Użyj	Gdzie leży checkout	Branch
Szybkie izolowane zadanie interaktywne	codex --worktree	$CODEX_HOME/worktrees/<id>/<repo> (domyślnie pod ~/.codex/)	Brak: odłączony HEAD na bieżącym commicie
Przenieść trwającą rozmowę do izolacji	/worktree w sesji („start or continue a conversation in a new worktree”)	To samo zarządzane miejsce	Brak, dopóki go nie utworzysz
Zadanie skryptowe, nieinteraktywne	codex exec --worktree albo git worktree add plus codex exec -C DIR	Zarządzane miejsce albo wybrana przez ciebie ścieżka	Brak przy codex exec --worktree (odłączony HEAD); nazwany przy git worktree add -b
Ścieżka, branch i baza pod twoją kontrolą (porty, skrypty CI, narzędzia do review)	git worktree add -b BRANCH PATH BASE, potem codex w tej ścieżce	Tam, gdzie go utworzysz	Nazwany od początku
Wątki w aplikacji desktopowej	Opcja worktree dla wątku w aplikacji (codex app, macOS i Windows)	Zarządza nim aplikacja	Zobacz pracę z aplikacją desktopową Codex

Istnieją też codex fork --worktree i codex resume --worktree (sprawdzone w --help, 0.157.1): kontynuują wcześniejszą sesję w nowym zarządzanym worktree. To czysty sposób, żeby wypróbować drugie podejście bez naruszania pierwszego.

Zasada praktyczna: --worktree do zadań jednorazowych i eksploracyjnych, git worktree add, gdy wynik ma się stać nazwanym branchem i pull requestem albo gdy skrypt, przydział portów czy ktoś z zespołu musi znaleźć checkout po ścieżce.

Co zarządzany worktree Codex przenosi z głównego checkoutu?

Uruchomiliśmy codex exec --worktree na Codex CLI 0.157.1 (2026-09-26) w repozytorium ze zmodyfikowanym śledzonym plikiem, nieśledzonym plikiem i .env w .gitignore. Zarządzany worktree zawierał:

Stan w głównym checkoucie	W zarządzanym worktree?
Zacommitowane pliki z HEAD	Tak, na tym samym commicie
Bieżący branch	Nie. Worktree ma odłączony HEAD
Niezacommitowane zmiany w śledzonych plikach	Nie. Plik ma zacommitowaną treść
Pliki nieśledzone	Nie
Pliki ignorowane (.env, node_modules/, cache buildów)	Nie

Wynikają z tego trzy rzeczy. Zacommituj (albo odłóż przez stash i nałóż z powrotem) wszystko, od czego zależy zadanie, zanim je uruchomisz. Licz się z tym, że każdy zarządzany worktree potrzebuje instalacji zależności i lokalnej konfiguracji. Utwórz branch, zanim agent zacznie commitować, bo commity na odłączonym HEAD nie należą do żadnego brancha i łatwo je stracić przy usuwaniu worktree.

Zarządzany worktree przeżywa też sesję: w tym samym teście git worktree list nadal go pokazywał po zakończeniu codex exec. codex --help w 0.157.1 nie ma podkomendy usuwającej worktree, więc usuwanie należy do Gita i można je wykonać z dowolnego checkoutu repozytorium.

Uruchom jedno zadanie Codex w izolowanym worktree

1. Sprawdź, od czego zacznie zadanie.

   git status --short        # nic z tej listy NIE trafi do nowego worktree
   git branch --show-current
   git worktree list         # istniejące worktrees, także te zarządzane przez Codex

   Zacommituj pracę, której zadanie potrzebuje. Jeśli nie chcesz commitować niedokończonego kodu, utwórz worktree z ostatniego dobrego commita i opisz brakujący element w prompcie.

2. Utwórz worktree. Wybierz jedną z dwóch form.

   Zarządzany, do szybkiego zadania:

   codex --worktree

   Sesja otwiera się w $CODEX_HOME/worktrees/<id>/<repo>. W drugim terminalu znajdź ten katalog przez git worktree list i uruchom w nim bootstrap, zanim wyślesz pierwszy prompt.

   Jawny, gdy branch i ścieżka mają być ustalone od początku:

   git fetch origin
   git worktree add -b codex/fix-auth-flake ../myapp-fix-auth-flake origin/main
   cd ../myapp-fix-auth-flake
   codex

   Zastąp origin/main faktycznym domyślnym branchem repozytorium (wypisze go git symbolic-ref refs/remotes/origin/HEAD). Git odmawia użycia brancha, który jest już aktywny (checked out) w innym worktree. To zaleta: dwóch agentów nie przejmie przypadkiem tego samego brancha.

3. Przygotuj checkout. Uruchom to w nowym worktree, we własnym terminalu, a nie przez agenta, żeby instalacja miała dostęp do sieci, którego sandbox nie daje:

   #!/usr/bin/env bash
   # bootstrap-worktree.sh: przygotuj świeży worktree do pracy
   set -euo pipefail
   MAIN=$(git worktree list --porcelain | awk 'NR==1 {print $2}')   # główny checkout jest zawsze pierwszy na liście
   for f in .env.development .env.test; do                          # tylko pliki deweloperskie, nigdy produkcyjne
     if [ -f "$MAIN/$f" ]; then cp "$MAIN/$f" .; fi
   done
   npm ci                                                           # instalacja z lockfile, bez ponownego rozwiązywania
   grep -qs '^PORT=' .env.development || echo "PORT=$((4000 + RANDOM % 1000))" >> .env.development   # port, którego raczej nie używa inny worktree; dopisany raz

   Skrypt można uruchamiać wielokrotnie: skopiuje te same pliki, zainstaluje zależności z lockfile i zachowa przydzielony już port. Trzymaj listę dozwolonych plików, jak wyżej. Kopiowanie wszystkich ignorowanych plików to prosta droga do klucza produkcyjnego w katalogu, który czyta agent. Jeśli repozytorium ma już skrypt setupu, wywołaj go tutaj. Gdy zadanie potrzebuje też własnej bazy danych lub zaślepek usług, daj mu pełny stos na zadanie, jak w efemerycznych środowiskach dla zadań agentów.

4. Uruchom zadanie z zawężonym promptem. Wklej pierwszy prompt poniżej. Prompt mówi Codeksowi, gdzie jest, czego może dotykać i co znaczy „gotowe”.

5. Udowodnij wynik, zanim go przeczytasz. Uruchom bramkę z sekcji Jak zweryfikować zadanie w worktree bez czytania każdej linii?. Diff czytaj dopiero wtedy, gdy bramka przejdzie, i tylko pliki, które wskaże.

6. Integruj zwykłą ścieżką. Wypchnij branch i otwórz pull request, żeby CI i reguły review działały tak samo jak dla pracy ludzi. Nie kopiuj plików między worktrees ręcznie i nie nakładaj przez git apply kilku patchy agentów na jeden branch bez ponownego uruchomienia bramek po każdym.

7. Usuń worktree dopiero, gdy praca jest bezpieczna. Zobacz sprzątanie worktrees Codex bez utraty commitów.

Prompt do skopiowania: start zadania w worktree

You are working in a dedicated Git worktree. Work only inside this directory.

First:
1. Run `git rev-parse --show-toplevel`, `git status --short` and `git branch --show-current`, and tell me what you found.
2. If HEAD is detached, create a branch with `git switch -c codex/fix-auth-flake` before changing anything.
3. Read AGENTS.md for the build, lint and test commands.

Task: make tests/auth/session-refresh.test.ts pass reliably. It fails about one run in five on CI. Find the cause (timer, shared state or ordering) before changing code; do not add retries or increase timeouts to hide it.

Rules:
- Do not touch files outside src/auth/ and tests/auth/ unless you stop and ask first.
- Do not install new dependencies, change the lockfile, or read or write any .env file.
- Do not push, merge, deploy, or remove this worktree.

Done means: the test passes 20 times in a row with `for i in $(seq 20); do npx vitest run tests/auth/session-refresh.test.ts || exit 1; done`, and type check, lint and the full test suite pass. End with each command you ran, its exit code, the root cause in two sentences, and the list of files you changed.

Dopasuj plik testu, ścieżki i polecenie powtórzeń do projektu. Skuteczność promptu wynika z jego struktury (lokalizacja, branch, zasady, warunek ukończenia z kodami wyjścia), dlatego sprawdzi się w każdym worktree.

Jak zweryfikować zadanie w worktree bez czytania każdej linii?

Worktree daje coś, czego współdzielony checkout nigdy nie da: diff należący do dokładnie jednego zadania. Wykorzystaj to. Uruchom te kontrole z worktree zadania, po kolei, i zatrzymaj się na pierwszym błędzie.

#!/usr/bin/env bash
# worktree-gate.sh BASE ALLOWED_PATHS_REGEX
# przykład: ./worktree-gate.sh origin/main '^(src/auth/|tests/auth/)'
set -euo pipefail
base="$1"; allowed="$2"

test -z "$(git status --porcelain)" || { echo "FAIL: uncommitted changes"; exit 1; }
git symbolic-ref -q HEAD >/dev/null   || { echo "FAIL: detached HEAD, create a branch"; exit 1; }

stray=$(git diff --name-only "$base"...HEAD | grep -v -E "$allowed" || true)
[ -z "$stray" ] || { echo "FAIL: files outside the task:"; echo "$stray"; exit 1; }

npm run typecheck                    # osobne wiersze: set -e zatrzymuje skrypt na pierwszej nieudanej kontroli
npm run lint
npm test

codex review --base "$base" || echo "WARN: codex review did not complete"   # doradczo: uwagi nigdy nie przerywają skryptu
echo PASS

codex review --base uruchamia wbudowany prompt review. W Codex CLI 0.157.1 nie przyjmuje dodatkowo własnych instrukcji: codex review --base main "..." kończy się błędem the argument '--base <BRANCH>' cannot be used with '[PROMPT]' (sprawdzone 2026-09-26), a --uncommitted ma to samo ograniczenie. Stałe reguły review, takie jak „oznacz zachowanie bez testu”, zapisz w AGENTS.md, a nie w wierszu poleceń. W tym skrypcie codex review ma rolę doradczą: wypisuje uwagi, a codex review --help w 0.157.1 nie opisuje kodu wyjścia, który zgłaszałby błąd przy uwagach, więc wiersz PASS oznacza, że przeszły kontrole mechaniczne. Gdy review w ogóle nie może się uruchomić (brak logowania, brak sieci), || echo wypisuje ostrzeżenie, zamiast pozwolić, by set -e przerwało skrypt. Przeczytaj jego wynik i traktuj wskazane pliki jako te, które czytasz ręcznie.

Kontrola	Co wyłapuje
Czysty status i nazwany branch	Pracę, która istnieje tylko w worktree i zniknęłaby przy jego usunięciu
Diff ograniczony do dozwolonych ścieżek	Agenta, który „naprawił” coś poza swoim zadaniem
Type check, lint, testy	Zepsute zachowanie, sprawdzone w izolacji od edycji innych zadań
codex review --base	Błędy logiki i brakujące testy, z drugiego przebiegu, który nie pisał tego kodu
CI na pull requeście	Wszystko powyższe jeszcze raz, na czystej maszynie, plus integrację z najnowszą bazą

Zatwierdzasz dwie rzeczy: warunek ukończenia w prompcie, zanim zadanie ruszy, oraz pliki, które bramka wskaże potem. Autoryzacja, płatności i migracje zawsze dostają ludzką lekturę, niezależnie od wyniku bramki. Warunek ukończenia działa najlepiej jako wykonywalne kryterium akceptacji (jak zamienić kryteria akceptacji w czerwone testy), a pull request powinien nieść pakiet dowodów, który musi przedstawić PR agenta. Jak skalować review w zespole, opisuje strona strategie review w Codex.

Prompt do skopiowania: oddaj worktree gotowy do merge'a

Prepare this worktree for review. Do not push, merge or delete anything.

1. Run `git status --short`. Commit every change that belongs to the task with a message that says what changed and why; list anything you did not commit and why.
2. Confirm HEAD is on a named branch, not detached.
3. Run `git diff --name-only origin/main...HEAD` and flag every file outside src/auth/ and tests/auth/.
4. Run type check, lint and the full test suite, and report each command with its exit code.
5. Write a pull request description: the problem, the root cause, the fix, how it was tested, and the risks a reviewer should check by hand.

Posprzątaj worktrees Codex bez utraty commitów

Każde zadanie zostawia checkout, a zarządzany leży w $CODEX_HOME/worktrees/, gdzie nie zauważysz, jak zapełnia dysk. Sprzątaj w tej kolejności:

git worktree list                                  # znajdź ścieżkę, także zarządzanych worktrees
git -C PATH status --short                         # musi być puste
git -C PATH log --oneline BASE..HEAD               # commity, których nie ma jeszcze w bazie
git branch -r --contains "$(git -C PATH rev-parse HEAD)"   # pusty wynik = nigdzie niewypchnięte
git worktree remove PATH
git worktree prune                                 # usuń wpisy o worktrees skasowanych w inny sposób

PATH to katalog worktree z git worktree list, a BASE to branch, od którego zadanie wystartowało, na przykład origin/main. git worktree remove odmawia usunięcia worktree ze zmodyfikowanymi lub nieśledzonymi plikami. Dodaj --force dopiero, gdy kontrola statusu i logu pokaże, że nie ma tam nic potrzebnego, bo ta flaga kasuje te pliki bezpowrotnie. Branch usuń na końcu przez git branch -d (odmawia usunięcia niezmergowanego brancha), a nie -D.

Gdy zadania Codex w worktrees zawodzą

Objaw	Przyczyna	Naprawa
Agent przy pierwszym poleceniu zgłasza brak modułów lub konfiguracji	Zarządzane i nowe worktrees nie dostają ignorowanych plików	Uruchom skrypt bootstrapu i zacznij zadanie od nowa
Zadanie nie widzi poprawki sprzed kilku minut	Worktree startuje z ostatniego commita, a nie z bieżącego stanu twojego katalogu roboczego	Zacommituj poprawkę, potem codex fork --worktree albo start od nowa
Commity zniknęły po sprzątaniu	Agent commitował na odłączonym HEAD; git worktree remove tego nie blokuje i kasuje własny reflog worktree	Zanim Git je usunie przy garbage collection, wypisz osierocone commity przez git fsck --lost-found, znajdź swój przez git show SHA, potem git branch rescue/TASK SHA. Zapobiegaj temu krokiem z branchem w pierwszym prompcie i kontrolą nazwanego brancha w bramce
Git zgłasza, że branch jest już aktywny (checked out) w innym worktree	Branch jest już aktywny (checked out) w innym worktree	Użyj nowej nazwy brancha albo najpierw usuń tamten worktree
Agent nie może commitować albo prosi o zgodę przy każdym zapisie git	Metadane Gita worktree leżą w .git/ głównego repozytorium, które może być poza obszarem zapisu sandboxa	Commituj z własnego terminala albo świadomie daj prawo zapisu do tego katalogu przez --add-dir (zobacz uprawnienia i sandboxing)
Codex pisze „The new worktree is not trusted; run Codex there.”	Nowa ścieżka checkoutu nie jest oznaczona jako zaufana, a projekty niezaufane nie dostarczają AGENTS.md (od Codex CLI 0.150.0)	Uruchom codex w worktree, zaakceptuj prośbę o zaufanie tylko dla repozytorium, któremu ufasz, i zacznij zadanie od nowa, żeby wczytało AGENTS.md
Dwa serwery deweloperskie walczą o jeden port	Każdy worktree odziedziczył ten sam PORT	Nadaj każdemu worktree własny port w bootstrapie i przekaż go serwerowi i testom end-to-end
Zmiany dwóch zadań konfliktują przy merge’u	Oba dotknęły wspólnego pliku (router, barrel export, schemat)	Zmerguj jedno, zrób rebase drugiego na nim i uruchom pełną bramkę. Następnym razem dziel zadania według własności plików, jak w wieloagentowych workflow
Dysk się zapełnia	Każdy worktree ma własne zależności i wyniki buildów, a zarządzane worktrees zostają po zakończeniu sesji	Raz w tygodniu usuwaj zakończone worktrees sekwencją sprzątania powyżej

Izolacja kończy się na systemie plików

Worktree rozdziela pliki, nie świat zewnętrzny. Zadania w różnych worktrees nadal współdzielą produkcyjną bazę danych, konta chmurowe, zewnętrzne API i wszystkie sekrety ze środowiska twojej powłoki. Nie wpuszczaj ich do bootstrapu i napisz agentowi w prompcie, których systemów zdalnych nie wolno mu dotykać. Baza danych na zadanie i zaślepki usług zamykają większość tej luki; strona o efemerycznych środowiskach z kroku 3 pokazuje, jak to zrobić.

Dokąd dalej z worktrees w Codex

• Przed tą stroną: skonfiguruj Codex i napisz AGENTS.md dla Codex, żeby każdy worktree znał polecenia buildu i testów.
• Dalej: wieloagentowe workflow w Codex, żeby prowadzić kilka zadań w worktrees jako równoległe tory, oraz Codex nieinteraktywnie przez codex exec, żeby je oskryptować.
• Zadania zbyt ciężkie na laptop: środowiska chmurowe Codex.
• Ta sama izolacja w Claude Code i Cursorze: równoległe agenty w izolowanych worktrees oraz narzędzia, które zarządzają wieloma naraz, w narzędziach do równoległych agentów.