SuperAPI AI Directory

worktree

Coding & development

View repository

Updated 10-15 21:34

About this skill

git worktree isolation skill

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 workspace node_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 install forbidden — because node_modules is a symlink, it pollutes the main checkout.
  • Deploy only via git push, vercel --prod CLI 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로 뜸 — gitignore node_modules/(directory pattern) does not hide symlinks. Never git add do 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 .