워크트리로 병렬 세션 실행하기

• ${CLAUDE_PROJECT_DIR}은 그대로: 세션이 시작된 프로젝트 루트를 계속 가리키므로 ${CLAUDE_PROJECT_DIR}/.claude/hooks/check-style.sh 같은 훅 명령은 여전히 기본 체크아웃의 스크립트를 실행합니다.
• cwd는 Claude를 따라감: 훅의 입력 JSON의 cwd 필드는 워크트리 루트이며, Claude가 cd를 실행하면 다시 이동합니다. 훅이 워크트리 경로를 필요로 하면 이 값을 읽으세요.

워크트리 정리

인터랙티브 워크트리 세션을 종료할 때 Claude는 제거 시 삭제될 워크트리의 작업을 검사합니다: 변경되거나 추적되지 않은 파일, 새 커밋이 그것입니다.

• 워크트리가 깨끗한 경우: 이름 없는 세션이면 Claude가 워크트리와 브랜치를 자동으로 제거합니다. 이름 있는 세션은 나중에 워크트리를 보존할 수 있도록 먼저 프롬프트를 띄웁니다.
• 워크트리에 작업이 있는 경우: Claude가 워크트리를 유지할지 제거할지 묻습니다. 유지는 디렉터리와 브랜치를 보존해 나중에 돌아올 수 있게 합니다. 제거는 워크트리 디렉터리와 브랜치, 그 안의 모든 작업을 지웁니다.

-p로 하는 비인터랙티브 실행은 종료 프롬프트가 없으므로 Claude가 해당 워크트리를 정리하지 않으며, Claude Code가 생성 시 각 워크트리에 걸어둔 락은 나중 세션의 stale-lock 정리가 해제할 때까지 유지됩니다. 제거하려면 git worktree remove를 실행하세요. git이 워크트리가 잠겨 있다며 거부하면 먼저 git worktree unlock을 실행하세요.

Windows에서 워크트리 제거는 그 밖의 파일을 삭제하지 않습니다. 워크트리 안 폴더가 NTFS junction이나 디렉터리 심볼릭 링크 같은 다른 곳으로의 링크라면 Claude Code는 링크만 삭제하고 가리키는 폴더는 유지합니다. v2.1.205 이전에는 하위 디렉터리에 중첩된 링크가 있는 워크트리를 제거하면 가리키는 폴더가 삭제될 수 있었습니다.

워크트리 세션 재개

워크트리 안에 있던 세션을 재개하면 Claude Code는 그 세션을 그 워크트리로 돌려보냅니다. 이는 인터랙티브 재개, -p를 쓴 비인터랙티브 모드의 --continue·--resume, 그리고 Agent SDK 모두에 해당합니다. 워크트리 안으로 돌아온 Claude는 여전히 ExitWorktree 도구로 빠져나갈 수 있습니다.

세션을 워크트리로 돌려보내기 전에 Claude Code는 워크트리가 여전히 기본 체크아웃과 분리된 체크아웃인지 검증하며, 검사를 통과하지 못한 워크트리 재진입을 거부합니다. git 워크트리의 경우 검사가 git 메타데이터를 읽습니다. WorktreeCreate 훅이 만든 것처럼 git 메타데이터가 없는 워크트리는 검사를 통과할 수 있습니다. Claude Code가 여전히 거부하는 경우는 Claude Code가 워크트리 사용을 거부에 복구 방법과 함께 나열됩니다. 메시지와 각각의 복구는 세션이 워크트리 밖에서 재개됨을 보세요.

어디서 시작하느냐와 어떻게 재개하느냐에 따라 Claude Code가 재진입하는 대상이 달라집니다:

• 시작 디렉터리: 기본 체크아웃이나 저장소의 다른 디렉터리에서 재개합니다. Claude Code는 .claude/worktrees/ 아래에 git으로 만든 워크트리를 시작 위치가 내부여도 재진입합니다. 다른 워크트리 내부에서 시작할 때는 Claude Code가 그곳에서 보증할 수 있을 때만 재진입합니다: 자체 저장소인 워크트리, git 메타데이터가 없는 워크트리, 또는 git worktree add로 만든 워크트리의 하위 디렉터리에서 시작하는 경우는 거부하므로 그런 경우엔 기본 체크아웃에서 시작하세요.
• --fork-session: 포크된 세션은 Claude를 실행한 디렉터리에서 시작하며, Claude Code는 원래 세션의 워크트리를 건드리지 않습니다.
• 삭제된 워크트리: 워크트리 디렉터리가 더 이상 없으면 Claude Code는 Claude를 실행한 디렉터리에서 세션을 재개합니다. 워크트리가 사라졌다고 알리고 세션의 워크트리 바인딩을 해제합니다.

Claude가 Claude Code가 git으로 만든 워크트리에 들어가거나 나오면 트랜스크립트가 따라갑니다: Claude Code는 /cd와 같은 방식으로 세션을 세션의 새 작업 디렉터리 아래에 기록하므로 /desktop과 --resume이 그곳에서 찾습니다. 나오면 같은 방식으로 다시 옮깁니다. WorktreeCreate 훅이 만든 워크트리는 시작 디렉터리에 트랜스크립트를 유지합니다. Claude Code v2.1.198 이상 필요.

Claude Code가 격리를 강제하는 방식

세션이 워크트리에서 격리되는 동안 Claude Code는 아래 검사가 정의하는 도구 호출을 차단합니다. --worktree로 세션을 시작했든, EnterWorktree로 Claude가 워크트리에 들어갔든, 워크트리 세션을 재개했든 동일한 규칙이 적용됩니다.

동일한 강제는 격리된 세션에서 Claude가 생성하는 모든 서브에이전트를 포함합니다. 세션이 인터랙티브든 백그라운드로 실행되든 적용됩니다. 자체 워크트리에서 실행되는 서브에이전트도 같은 검사를 갖습니다. 버전 이력은 Write subagent files에 있습니다.

Claude Code는 네 가지 검사를 적용합니다:

• 파일 편집: 기본 체크아웃의 경로를 대상으로 하는 Edit, Write, NotebookEdit를 차단합니다.
• 명령 작업 디렉터리: 작업 디렉터리가 기본 체크아웃으로 해석되거나, 그 밖에 머무르는지 검증할 수 없는 Bash·PowerShell·Monitor 명령을 차단합니다.
• git 리다이렉션: git을 기본 체크아웃으로 리다이렉트하는 Bash·Monitor 명령을 차단합니다. 리다이렉트는 git -C, --git-dir, GIT_DIR·GIT_WORK_TREE 변수, 또는 git 실행 전 기본 체크아웃으로의 cd를 통해 올 수 있습니다.
• 명령 형태: 명령 텍스트만으로 실행되는 git이 워크트리 안에 머무르는지 검증할 수 없으면(예: 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없을 때) Bash·Monitor 명령을 차단합니다. Claude Code는 차단된 명령을 일반적인 별도 명령으로 나누는 등 어떻게 고쳐 써야 하는지 알려줍니다. 이 검사는 끌 수 없습니다.

검사는 Claude Code를 실행한 저장소에 적용됩니다. 연결된 워크트리가 연결된 기본 체크아웃도 포함합니다. PowerShell 명령에는 작업 디렉터리 검사만 적용합니다.

Claude는 각 거부를 워크트리 이름과 진행 방법을 말하는 도구 오류로 봅니다.

서브에이전트 워크트리 격리

서브에이전트는 자체 워크트리에서 실행될 수 있어 병렬 편집이 충돌하지 않습니다. Claude에게 "use worktrees for your agents"라고 요청하거나, 커스텀 서브에이전트에 isolation: worktree를 프런트매터에 추가해 영구적으로 격리를 만들 수 있습니다.

.claude/agents/의 이 서브에이전트는 항상 자체 워크트리에서 실행됩니다:

---
name: refactorer
description: Applies mechanical refactors across many files
isolation: worktree
---

Apply the requested refactor across every affected file, then run the tests
and report the results.

각 서브에이전트는 임시 워크트리를 받으며, Claude Code는 서브에이전트가 변경 없이 끝나면 자동으로 제거합니다. 변경이 있는 워크트리는 아래 주기적 정리가 작업을 잃지 않고 제거할 수 있을 때까지 디스크에 남습니다.

서브에이전트 워크트리는 --worktree와 같은 기본 브랜치를 사용하므로 worktree.baseRef가 "head"로 설정되지 않았다면 저장소의 기본 브랜치에서 분기합니다.

서브에이전트 및 백그라운드 세션 워크트리 정리

Claude Code는 주기적 정리를 실행해 서브에이전트와 백그라운드 세션를 위해 만든 워크트리를 cleanupPeriodDays 설정보다 오래되면 제거하며, 보존 정리 규칙을 따릅니다.

--worktree 세션을 백그라운드로 보내면 그 워크트리는 정리가 제거할 수 있는 백그라운드 세션 워크트리가 됩니다. 정리는 다음 경우 워크트리를 그대로 둡니다:

• 워크트리에 여전히 작업이 있는 경우: 변경되거나 추적되지 않은 파일, 또는 푸시되지 않은 커밋.
• Claude Code가 저장소 설정이 정의하는 필터 드라이버를 판별할 수 없는 경우(워크트리 생성도 막는 세 가지 경우 중 하나).
• 백그라운드로 보내지 않은 --worktree 세션에 속한 워크트리(나이와 무관).
• git worktree add로 직접 만든 워크트리(그런 다음 --worktree <name> 세션을 실행하고 백그라운드로 보냈더라도).

Claude Code는 git으로 만드는 모든 워크트리의 git 메타데이터에 마커를 쓰며, 정리는 마커가 없는 워크트리(WorktreeCreate 훅이 만든 워크트리 포함)를 유지합니다. v2.1.246 이전에는 정리가 마커를 확인하지 않아, 오래된 백그라운드 세션 레코드가 가리키면 직접 만든 워크트리를 제거할 수 있었습니다.

에이전트가 실행되는 동안 Claude Code는 워크트리에 git worktree lock을 걸어 동시 정리가 제거하지 못하게 하며, 에이전트가 끝나면 락을 해제합니다. Claude Code는 백그라운드로 보낸 세션을 위해 만든 워크트리에도 세션 실행 중 같은 락을 걸므로 정리가 워크트리를 그대로 두고 git worktree remove는 제거를 거부합니다.

또한 정리는 프로세스가 종료된 세션에 대해 Claude Code가 건 락도 해제하므로, 죽은 백그라운드 세션이 워크트리를 영구히 잠그지 않습니다. 정리는 사용자가 git worktree lock으로 직접 건 락은 절대 해제하지 않습니다. v2.1.210 이전에는 죽은 세션이 남긴 락이 git worktree unlock을 실행할 때까지 유지되었습니다.

정리가 유지하는 워크트리를 정리하려면 git worktree remove를 실행하되, 워크트리에 커밋되지 않은 변경이나 추적되지 않은 파일이 있으면 --force를 추가하세요. git이 잠겼다며 거부하면 먼저 git worktree unlock을 실행하세요.

워크트리 생성 커스터마이즈

Claude Code의 워크트리 생성 기본값은 대부분의 세션을 충족합니다: .claude/worktrees/ 아래에 만들고, 저장소의 기본 브랜치에서 분기하며, 추적된 파일만 체크아웃합니다. 이 절의 옵션은 그 기본값을 바꿉니다.

기본 브랜치 선택

새 워크트리는 저장소의 기본 브랜치에서 분기하므로 대부분의 세션은 이 설정이 필요 없습니다. settings에서 worktree.baseRef를 설정해 대신 현재 작업에서 분기하게 하세요. 설정은 두 값을 받습니다:

• "fresh"(기본값): 리모트의 저장소 기본 브랜치(보통 main)에서 분기하므로 워크트리는 리모트와 일치하는 깨끗한 트리에서 시작합니다.
• "head": 현재 로컬 HEAD에서 분기하므로 워크트리가 푸시되지 않은 커밋과 기능 브랜치 상태를 가져옵니다. 진행 중인 작업에서 동작해야 하는 서브에이전트를 격리할 때 쓰세요. 워크트리 안에서 "head"는 기본 체크아웃의 HEAD가 아니라 그 워크트리의 HEAD로 해석됩니다.

worktree.baseRef를 브랜치 이름으로 설정할 수는 없습니다. 특정 기존 브랜치에서 워크트리를 시작하려면 git으로 직접 만들면 됩니다.

"fresh" 베이스의 경우 Claude Code는 origin/HEAD를 최신으로 유지합니다: 저장소를 지난 24시간 내에 fetch하지 않았다면 기본 브랜치를 fetch하며(최대 5초), fetch가 실패하면 로컬 캐시된 ref를 사용합니다. 리모트가 없거나 origin/HEAD가 로컬에 캐시되지 않았고 fetch할 수 없으면 워크트리는 현재 로컬 HEAD로 폴백합니다. v2.1.208 이전에는 fresh 워크트리가 로컬에 이미 캐시된 origin/HEAD를 사용했습니다.

이 예시는 모든 새 워크트리가 현재 작업에서 분기하게 합니다:

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

풀 리퀘스트에서 분기

특정 풀 리퀘스트나 머지 리퀘스트에서 분기하려면 --worktree에 #가 붙은 번호, GitHub 풀 리퀘스트 URL, 또는 https://gitlab.com/group/repo/-/merge_requests/123 같은 GitLab 머지 리퀘스트 URL을 전달하세요. Claude Code는 origin에서 그 변경의 head 커밋을 fetch하고 .claude/worktrees/pr-<number>에 워크트리를 만듭니다. 셸이 #을 주석 시작으로 취급하지 않도록 인수를 따옴표로 감싸세요:

claude --worktree "#1234"

Claude Code는 URL에서 번호만 읽습니다. 항상 저장소의 origin 리모트에서 fetch하며, origin 호스트에 따라 fetch 경로를 고릅니다:

• github.com: pull/<number>/head fetch
• gitlab.com: merge-requests/<number>/head fetch
• GitHub Enterprise, 셀프 매니지드 GitLab, 기타 호스트: 먼저 pull/<number>/head를 시도한 후 merge-requests/<number>/head 시도

v2.1.233 이전에는 Claude Code가 --worktree에 #<number>와 GitHub 스타일 풀 리퀘스트 URL만 받았고 항상 pull/<number>/head를 fetch했습니다.

gitignored 파일 워크트리 복사

워크트리는 새 체크아웃이므로 메인 저장소의 .env나 .env.local 같은 추적되지 않은 파일은 없습니다. Claude가 워크트리를 만들 때 자동으로 복사하려면 프로젝트 루트에 .worktreeinclude 파일을 추가하세요.

파일은 .gitignore 구문을 사용합니다. 패턴과 일치하면서 gitignored인 파일만 복사되므로 추적된 파일은 결코 중복되지 않습니다.

**/로 시작하는 패턴을 쓰는데 원하는 파일이 전체적으로 gitignored된 디렉터리 안에 있다면, Claude Code는 그 디렉터리 자체가 패턴과 일치하거나 **/ 뒤 첫 이름이 디렉터리 경로의 이름 중 하나일 때만 복사합니다. 예를 들어 **/.claude/skills/*.md를 쓰면 그 첫 이름은 .claude이므로 Claude Code는 무시된 .claude/ 디렉터리에서 일치하는 파일을 복사합니다. **/ 패턴이 닿지 않는 무시된 디렉터리에서 파일을 복사하려면 대신 패턴에서 디렉터리를 이름으로 쓰세요: **/config.json보다 vendor/**/config.json처럼. v2.1.239 이전에는 완전히 무시된 디렉터리의 파일을 **/ 패턴으로 디렉터리 자체가 패턴과 일치할 때만 복사했습니다.

이 .worktreeinclude는 두 env 파일과 시크릿 설정을 각 새 워크트리로 복사합니다:

.env
.env.local
config/secrets.json

이는 Claude Code가 git으로 만드는 모든 워크트리, 즉 --worktree 워크트리, 서브에이전트 워크트리, 데스크톱 앱의 병렬 세션에 적용됩니다. WorktreeCreate 훅을 쓰면 훅 스크립트 안에서 파일을 복사하세요.

워크트리 이름 재사용

디렉터리가 이미 존재하는 이름으로 --worktree를 전달하면 새 워크트리를 만드는 대신 기존 워크트리를 엽니다.

기본 "fresh" 베이스에서 재열린 워크트리는 다음 조건이 모두 성립할 때 옛 tip에서 계속하는 대신 저장소의 기본 브랜치로 재설정됩니다:

• 커밋되지 않은 변경이나 추적되지 않은 파일이 없음.
• 여전히 Claude Code가 만든 브랜치에 있음.
• 자체 커밋이 없거나, 풀 리퀘스트/머지 리퀘스트가 머지되고 리모트 브랜치가 삭제됨.

Claude Code는 git 상태만으로 머지된 경우를 감지합니다: 워크트리가 푸시한 리모트 브랜치가 더 이상 존재하지 않고, 워크트리의 모든 커밋이 이미 기본 브랜치에 있습니다.

그 외 모든 경우 Claude Code는 워크트리를 옛 tip에서 재엽니다:

• 워크트리가 조건 중 하나라도 실패.
• Claude Code가 워크트리 상태를 검증할 수 없음.
• worktree.baseRef가 "head".
• 이름이 풀 리퀘스트나 머지 리퀘스트 참조.

v2.1.208 이전에는 이름을 재사용하면 Claude Code가 항상 옛 워크트리를 옛 tip에서 재열었습니다.

훅으로 워크트리 생성 대체

WorktreeCreate 훅을 구성해 기본 git worktree 로직 전체를 대체할 수 있으며, 워크트리를 .claude/worktrees/가 아닌 곳에 두는 것도 포함합니다. 완전한 예시는 비-git 버전 관리를 보세요.

워크트리가 기본 체크아웃과 공유하는 것

워크트리는 자체 파일과 브랜치를 얻지만 저장소의 .git 디렉터리, 프로젝트 스코프 플러그인, 저장된 권한 승인을 기본 체크아웃과 공유합니다:

• 저장소의 .git 디렉터리: 워크트리의 git 명령은 메인 저장소의 공유 .git 디렉터리에 쓰며, 샌드박싱은 그 쓰기를 허용하므로 샌드박스를 켠 상태에서도 워크트리 안에서 git commit 같은 명령이 동작합니다.
• 플러그인: 기본 체크아웃에서 프로젝트 스코프로 설치한 플러그인은 같은 저장소의 워크트리에서도 로드되므로 워크트리마다 다시 설치할 필요가 없습니다. Claude Code v2.1.200 이상 필요.
• 권한 승인: 워크트리 세션에서 Bash 명령에 "Yes, and don't ask again"을 선택하면 그 규칙이 기본 체크아웃의 .claude/settings.local.json에 저장되어 기본 체크아웃과 저장소의 모든 워크트리에 적용되며 워크트리 제거 후에도 남습니다. Windows와 Claude Code가 저장소 루트를 사용하지 않는 다른 경우에는 규칙이 그 워크트리에 남습니다. v2.1.211 이전에는 워크트리에서 부여된 승인이 그 워크트리 안에 저장되어 다른 곳에 적용되지 않았고 워크트리 제거 시 유실되었습니다. 승인이 저장되는 위치를 보세요.

세 가지 모두 --worktree로 생성했든, git worktree add로 했든, 데스크톱 앱을 통했든 적용됩니다.

워크트리 수동 관리

특정 기존 브랜치를 체크아웃하거나 워크트리를 저장소 밖에 두어야 할 때는 Git으로 직접 워크트리를 만드세요.

새 브랜치에 워크트리 만들기:

git worktree add ../project-feature-a -b feature-a

기존 브랜치에서 워크트리 만들기(fix-issue-456을 저장소에 이미 있는 브랜치로 교체):

git worktree add ../project-bugfix fix-issue-456

워크트리에서 Claude 시작:

cd ../project-feature-a
claude

워크트리 나열:

git worktree list

다 쓴 워크트리 제거:

git worktree remove ../project-feature-a

전체 명령 참조는 Git worktree 문서를 보세요.

비-git 버전 관리

워크트리 격리는 기본적으로 git을 사용합니다. SVN, Perforce, Mercurial 또는 기타 시스템에서는 WorktreeCreate와 WorktreeRemove 훅을 구성해 커스텀 생성·정리 로직을 제공하세요. 훅이 기본 git 동작을 대체하므로 --worktree를 쓸 때 .worktreeinclude는 처리되지 않습니다. 로컬 설정 파일은 훅 스크립트 안에서 복사하세요.

이 WorktreeCreate 훅은 jq로 stdin의 JSON에서 워크트리 이름을 읽고, fresh SVN 워킹 카피를 체크아웃한 뒤 디렉터리 경로를 출력해 Claude Code가 세션의 작업 디렉터리로 쓰게 합니다. settings.json에 설정을 추가하세요:

{
  "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\"'"
          }
        ]
      }
    ]
  }
}

세션 종료 시 정리할 WorktreeRemove 훅과 짝지으세요. 입력 스키마와 제거 예시는 hooks 참조를 보세요.

트러블슈팅

Claude Code는 워크트리를 만들 때, 시작 시 들어갈 때, 또는 재개한 세션을 돌려보낼 때 아래 오류를 보고합니다.

시작 시 워크트리에 들어갈 수 없음

시작 시 워크트리 디렉터리에 들어갈 수 없으면 Claude Code는 경로를 명명하는 오류를 출력하고 코드 1로 종료합니다. WorktreeCreate 훅이 만든 디렉터리가 아닌 다른 것을 출력하거나, 설정 후 디렉터리가 삭제됐을 때 발생할 수 있습니다.

심볼릭 링크 경로에서 워크트리 생성 실패

.claude, .claude/worktrees, 또는 워크트리 디렉터리 자체가 심볼릭 링크일 때 Claude Code는 워크트리 생성을 거부하며 오류가 심볼릭 링크 경로를 명명합니다. 심볼릭 링크를 제거하고 재시도하세요. v2.1.212 이전에는 저장소에 그 경로 중 하나에 커밋된 심볼릭 링크가 이미 있으면 워크트리 생성이 그것을 따라가 저장소 밖에 파일을 만들 수 있었습니다.

Git LFS 파일이 Claude Code가 만든 워크트리에서 포인터 파일인 경우

git lfs install --local로 Git LFS를 설정했다면 Claude Code가 만든 워크트리는 실제 파일 대신 LFS 포인터 파일을 포함합니다. --local 플래그는 LFS 필터를 전역 git config가 아니라 저장소 자체의 .git/config에 씁니다. 일반 git lfs install은 전역 config에 쓰므로 영향을 받지 않습니다. 저장소 자체 config에 정의된 다른 필터 드라이버에도 동일하게 적용됩니다.

Claude Code는 워크트리를 만들 때 저장소 자체의 필터 드라이버를 건너뜁니다. 필터 드라이버는 셸 명령이고, Claude를 포함해 저장소에 쓸 수 있는 무엇이든 그곳에 넣을 수 있기 때문입니다. v2.1.247 이전에는 Claude Code가 워크트리 생성 중에 그 드라이버를 실행했습니다.

실제 파일을 얻으려면 워크트리 안에서 git lfs pull을 실행하세요.

세 가지 드문 경우에 Claude Code는 저장소 config가 정의하는 필터 드라이버를 판별하지 못해 워크트리를 전혀 만들지 않습니다. 오류에 맞는 수정을 고르세요:

• Could not read the repository git config to neutralize filter drivers: Claude Code가 저장소의 .git/config를 읽지 못했습니다(예: 권한 때문). 고치고 재시도하세요.
• The repository git config defines a filter driver whose name cannot be neutralized (contains "=" or a newline): .git/config에서 그 필터 드라이버를 이름 바꾸거나 제거하고 재시도하세요.
• The repository git config has a conditional include (includeIf): .git/config의 includeIf가 끌어오는 설정을 그 파일에 직접 옮기고 includeIf를 제거한 후 재시도하세요. 전역 git config의 includeIf는 이를 유발하지 않습니다.

Claude Code가 워크트리 사용을 거부

Refusing to use <path> as an isolation worktree로 시작하는 오류는 Claude Code가 세션·서브에이전트의 격리 체크아웃으로 채택하기 전에 디렉터리의 git 정체성을 검사하고 거부했음을 의미합니다. 이 검사는 워크트리를 만들 때, 기존 항목에 들어갈 때, 이전 실행에서 재사용할 때 모두 실행됩니다.

대부분의 경우 메시지의 나머지는 디렉터리의 git 메타데이터가 기본 체크아웃으로 해석됨을 말합니다: 예를 들어 .git 파일이 메인 저장소의 .git 디렉터리를 가리키거나, git이 core.worktree 리다이렉트를 통해 작업 트리를 기본 체크아웃으로 해석합니다. 그런 디렉터리에서 git reset --hard 같은 일반 git 명령은 워크트리 대신 기본 체크아웃에 작용합니다. Claude Code는 디렉터리에 읽을 수 없는 .git 항목이 있을 때도 워크트리가 안전하다고 가정하지 않고 거부합니다.

git 메타데이터가 전혀 없는 디렉터리(예: WorktreeCreate 훅이 만든 것)는 그 디렉터리를 포함하는 git 저장소가 없을 때만 검사를 통과합니다. 훅이 저장소 안에 디렉터리를 만들면 git이 그 저장소의 체크아웃으로 해석하고 Claude Code는 git resolves its working tree to 메시지로 거부하므로, 훅이 디렉터리를 어떤 저장소 밖에 만들도록 하세요.

Claude Code는 거부된 디렉터리를 그대로 둡니다(작업을 담고 있을 수 있으므로). 메시지가 Refusing to use <path> 뒤에 나오든 재개 메시지에 나오든, 메시지에 맞는 복구를 고르세요. 일부 끝맺음은 재개 메시지에서만 나타납니다:

• launch from the parent checkout 또는 Run the resume from the project checkout이라고 말함: 워크트리 안에서 Claude Code를 시작했습니다. 대신 기본 체크아웃에서 시작하세요. 워크트리는 재생성이 필요 없습니다.
• it cannot be resumed or re-entered라고 말함: 이 세션에서 시작 위치로부터 워크트리를 보증할 수 없습니다. 재생성하세요. 디렉터리와 그 작업은 수동 복구를 위해 디스크에 남아 있으며, 워크트리에 부모 체크아웃이 있으면 거기서 재개해도 동작합니다.
• it contains the protected checkout라고 말함: 거부된 디렉터리가 기본 체크아웃의 부모(예: 홈 디렉터리)입니다. 삭제하지 마세요. 워크트리가 체크아웃을 포함하지 않도록 WorktreeCreate 훅이 반환하는 경로나 EnterWorktree 대상 같은 워크트리 경로를 바꾸세요.
• the protected checkout <path> has a .git entry that could not be examined 또는 has git metadata that could not be resolved라고 말함: 문제는 워크트리가 아니라 기본 체크아웃의 git 메타데이터입니다. 워크트리를 삭제하지 말고, 이 두 끝맺음에는 적용되지 않는 재생성하라는 메시지의 뒤쪽 조언은 무시하세요. 권한 문제나 .git에 대한 git dubious ownership 거부 같은 기본 체크아웃의 문제를 고치고 재시도하세요.
• its recorded path has a network spelling이라고 말함: Claude Code는 네트워크 경로의 워크트리로 재개하지 않습니다. 로컬 경로에 워크트리를 재생성하세요.
• 기타 끝맺음: 메시지가 문제와 해결책(예: core.worktree 리다이렉트 제거, 워크트리 재생성)을 명명합니다. 따르세요. git 정체성을 검증할 수 없다고 하는 메시지의 디렉터리를 삭제하기 전에 먼저 명명된 원인(예: 워크트리 경로의 심볼릭 링크, git 자체 실행 실패)을 해결하세요. 디렉터리는 정상일 수 있으니까요. 재생성할 때는 먼저 옛 디렉터리에서 필요한 변경을 구출하세요. 디스크에 남습니다.

세션이 워크트리 밖에서 재개됨

인터랙티브로 세션을 재개했는데 Claude Code가 워크트리로 돌려보낼 수 없으면 아래 메시지 중 하나로 알립니다. Claude Code가 워크트리 바인딩을 해제하면 세션 트랜스크립트에 해제를 기록합니다. 트랜스크립트 쓰기 억제를 켰다면 대신 바인딩을 해제할 수 없다고 말하고, 이후 재개 시 워크트리를 다시 확인한다고 말합니다.

-p를 쓰는 비인터랙티브 모드와 Agent SDK가 실행하는 재개에서는, 사라진 워크트리를 제외한 모든 거부에 대해 격리 없이 계속하는 대신 stderr 오류로 재개를 중단합니다.

--output-format stream-json을 쓰면 거부가 stdout에도 result 메시지(subtype error_during_execution)로 도착하며 그 errors 배열이 같은 텍스트를 전달하므로 Agent SDK 애플리케이션이 0이 아닌 종료 코드만이 아니라 이유를 받습니다. v2.1.260 이전에는 워크트리 재개 거부가 result 메시지를 만들지 않았습니다.

메시지는 표의 인터랙티브 메시지와 다른 형태를 취합니다:

• Error: cannot resume into worktree <path>: ...This session was not started. — 표에서 Did not re-enter로 표시된 거부. Claude Code는 종료 전에 워크트리 바인딩을 해제하고 오류가 그렇게 말합니다. 대화를 다음에 재개하면 세션은 워크트리 격리 없이 현재 디렉터리에서 계속됩니다. v2.1.260 이전에는 Claude Code가 해제된 바인딩을 쓰지 않아, 같은 재개를 재시도할 때마다 같은 오류로 실패했습니다.

  트랜스크립트 쓰기 억제를 켜면 해제를 저장할 수 없습니다. 그러면 오류가 같은 명령이 다시 거부될 것이라고 말하고, 워크트리 없이 계속하는 방법으로 --fork-session과 새 대화 시작을 명명합니다.

• Error: could not verify worktree <path> for this resume, so the resume was aborted... — Could not verify에 해당.

• Error: ...The worktree binding is kept. — Could not re-enter에 해당.

• Notice: the worktree <path> for this session no longer exists... — 사라진 워크트리. Claude Code가 출력하고 인터랙티브 재개처럼 세션을 계속합니다.

각 오류에 포함된 거부 끝맺음은 인터랙티브 알림과 공유되므로 Claude Code가 워크트리 사용을 거부의 항목과 여전히 대응됩니다.

더 알아보기

워크트리는 파일 격리를 처리합니다. 관련 페이지는 그 격리된 체크아웃으로 작업을 위임하고, 그 사이에서 발견 내용을 전달하고, 만든 세션 사이를 전환하는 것을 다룹니다:

• 서브에이전트 (Subagents): 세션 안에서 격리된 에이전트로 작업 위임
• 세션 간 메시징 (Cross-session messaging): 워크트리의 세션들이 발견 내용을 서로 전달
• 에이전트 팀 (Agent teams): 여러 Claude 세션 자동 조율
• 세션 관리 (Manage sessions): 대화 이름 짓기, 재개, 전환
• 데스크톱 병렬 세션 (Desktop parallel sessions): 데스크톱 앱의 워크트리 기반 세션