When running multiple Claude/Codex sessions simultaneously, sharing the main checkout means overwriting each other's uncommitted changes and.next build caches silently. Giving each session an isolated worktree physically separates source, build, and state, blocking conflicts at the source.
Why: On 2026-06-10, two Claude sessions worked simultaneously in the main checkout → one side's edit nearly overwrote the other's. Recurrence blocked by worktree isolation.
Scripts (install paths)
# Claude Code
~/.claude/skills/worktree/scripts/wt-new.sh <branch> [base=main]
~/.claude/skills/worktree/scripts/wt-ls.sh [--mine|--prune]
~/.claude/skills/worktree/scripts/wt-done.sh <branch> [--force]
# Codex
~/.codex/skills/worktree/scripts/wt-new.sh <branch> [base=main]
The same tools committed to the repo are also at scripts/tools/wt-*.sh(eoash only). The scripts find the repo root via git rev-parse --show-toplevel, so whichever git repo the CWD is in, it operates on that repoaccordingly.
Standard workflow
# 1) 세션용 worktree 생성 (origin/main 에서 새 브랜치 분기 + node_modules 심링크)
~/.claude/skills/worktree/scripts/wt-new.sh fix/foo
# 2) 그 디렉토리에서 새 세션 시작 → 메인·타 세션과 충돌 0
cd ~/Documents/<repo>-worktrees/fix-foo && claude
# 3) 작업 → 커밋 → 푸시 → PR (worktree 안에서)
git add <파일> && git commit -m "..." && git push -u origin fix/foo && gh pr create
# 4) PR 머지 후 정리
~/.claude/skills/worktree/scripts/wt-done.sh fix/foo
Behavior summary
- wt-new: create worktree in a sibling outside the repo
<repo>-worktrees/<slug>,origin/<base>branch from (or check out if the branch already exists). Root + each workspacenode_modules·.envin the main checkout symlink(no npm install/cp needed). - wt-ls: full worktree status —
clean/DIRTY(uncommitted)/↑N(unpushed)/PRUNABLE(directory gone).--mineonly shows the ones this skill created,--prunecleans up zombies. - wt-done: removes only if the uncommitted/unpushed guard passes (
--forceto force). Branch refs and commits are preserved (only the working directory is deleted).
🚨 Guardrails / Pitfalls (must follow)
- In a worktree,
npm installforbidden — because node_modules is a symlink, it pollutes the main checkout. - Deploy only via git push,
vercel --prodCLI forbidden — symlinked node_modules, when uploaded via the CLI,ENOTDIR,.vercelignore !.gitbreaks due to the fsmonitor socket. Remote git-integration builds use a clean checkout, so they are unaffected. - Removing a clean worktree loses 0 commits —
git worktree removedeletes only the working directory, leaving branch refs and commits in.git. The real danger is only **DIRTY (uncommitted)**. - Symlinked node_modules
git status에?? node_modules로 뜸 — gitignorenode_modules/(directory pattern) does not hide symlinks. Nevergit adddo it. wt-ls/wt-done exclude this noise via path-based filtering. - npm workspaces self-reference — root
node_modules/<ws>points to the main source. Building the app directly (cd <app> && next build) is caught in CWD·@/*and is safe. Importing the workspace by package name can read the main source.
Detailed pitfall catalog and design decisions: see repo docs/git-worktree-parallel.md .