worktree를 사용하여 병렬 세션 실행

​

worktree에서 Claude 시작

claude --worktree feature-auth

​

worktree 환경 설정

​

Claude에게 worktree 생성 요청

​

worktree 정리

• Worktree가 깨끗함: 이름 없는 세션의 경우 Claude는 worktree와 해당 브랜치를 자동으로 제거합니다. 이름이 지정된 세션은 나중을 위해 worktree를 유지할 수 있도록 먼저 프롬프트를 표시합니다.
• Worktree에 작업이 있음: Claude는 worktree를 유지하거나 제거할지 묻습니다. 유지하면 디렉토리와 브랜치가 보존되어 나중에 돌아올 수 있습니다. 제거하면 worktree 디렉토리와 해당 브랜치가 삭제되며, 그 안의 모든 작업도 함께 삭제됩니다.
• Worktree의 상태를 확인할 수 없음: Claude Code가 worktree의 변경 사항을 계산할 수 없거나 서브모듈 체크아웃을 검사할 수 없을 때, worktree를 자동으로 제거하지 않고 프롬프트를 표시합니다. 프롬프트는 확인할 수 없었던 항목을 명시합니다.

​

worktree 세션 재개

• 실행 디렉토리: 메인 체크아웃 또는 저장소의 다른 디렉토리에서 재개합니다. Claude Code는 실행 위치 내부에서 실행하더라도 .claude/worktrees/ 아래에서 git으로 생성한 worktree로 다시 들어갑니다. 다른 worktree 내부에서 실행할 때 Claude Code는 거기서 이를 보증할 수 있는 경우에만 다시 들어갑니다: 자체 저장소인 worktree, git 메타데이터가 없는 worktree, 또는 git worktree add로 생성한 worktree의 서브디렉토리에서 실행하면 거부되므로 메인 체크아웃에서 실행합니다.
• --fork-session: 포크된 세션은 Claude를 실행한 디렉토리에서 시작하며 Claude Code는 원본 세션의 worktree를 그대로 둡니다.
• 삭제된 worktree: worktree 디렉토리가 더 이상 존재하지 않으면 Claude Code는 Claude를 실행한 디렉토리에서 세션을 재개합니다. Worktree가 없어졌음을 알려주고 세션의 worktree 바인딩을 지웁니다.

​

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

• 파일 편집: Claude Code는 메인 체크아웃의 경로를 대상으로 하는 Edit, Write 또는 NotebookEdit을 차단합니다.
• 명령 작업 디렉토리: Claude Code는 작업 디렉토리가 메인 체크아웃으로 확인되거나 그 외부에 머물러 있는지 확인할 수 없는 Bash, PowerShell 또는 Monitor 명령을 차단합니다.
• Git 리다이렉트: Claude Code는 git을 메인 체크아웃으로 리다이렉트하는 Bash 또는 Monitor 명령을 차단합니다. 리다이렉트는 git -C, --git-dir, GIT_DIR 또는 GIT_WORK_TREE 변수, 또는 git을 실행하기 전에 메인 체크아웃으로 cd를 통해 올 수 있습니다.
• 명령 형태: Claude Code는 명령 텍스트에서 명령이 실행하는 모든 git이 worktree 내부에 머물러 있는지 확인할 수 없을 때 Bash 또는 Monitor 명령을 차단합니다. 예를 들어 명령 이름이 런타임에 계산되거나 구문을 파싱할 수 없거나 ${!name} 또는 ${ command; }와 같은 확장이 텍스트에서 명시하지 않은 명령을 실행할 수 있을 때 발생합니다. Claude Code는 Claude에게 거부된 명령을 다시 작성하는 방법을 알려줍니다. 예를 들어 이를 일반 별도 명령으로 분할합니다. 이 확인을 끌 수 없습니다.

​

worktree로 서브에이전트 격리

---
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.

​

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

• Worktree가 여전히 작업을 보유하고 있습니다: 변경되거나 추적되지 않은 파일, 또는 푸시되지 않은 커밋.
• worktree의 체크아웃된 서브모듈이 변경되거나 추적되지 않은 파일을 보유하고 있거나, Claude Code가 worktree의 서브모듈을 검사할 수 없습니다. 이 확인에는 Claude Code v2.1.274 이상이 필요합니다.
• worktree 생성을 차단하는 네 가지 경우 중 하나가 적용됩니다: Claude Code가 저장소 구성이 정의하는 필터 드라이버를 결정할 수 없거나, 여기서 전환할 수 없는 설정을 찾습니다.
• Worktree가 백그라운드하지 않은 --worktree 세션에 속합니다. 나이와 관계없이.
• git worktree add로 직접 worktree를 생성했습니다. 나중에 --worktree <name> 세션을 실행하고 해당 세션을 백그라운드했더라도.

​

worktree 생성 사용자 정의

​

기본 브랜치 선택

• "fresh" (기본값): 원격의 저장소 기본 브랜치(보통 main)에서 분기하므로 worktree는 원격과 일치하는 깨끗한 트리에서 시작합니다.
• "head": 현재 로컬 HEAD에서 분기하므로 worktree는 푸시되지 않은 커밋과 기능 브랜치 상태를 유지합니다. 진행 중인 작업에서 작동해야 하는 서브에이전트를 격리할 때 사용합니다. Worktree 내부에서 "head"는 메인 체크아웃의 HEAD가 아닌 해당 worktree의 HEAD로 확인됩니다.

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

​

풀 요청에서 분기

claude --worktree "#1234"

• github.com: pull/<number>/head 페치
• gitlab.com: merge-requests/<number>/head 페치
• GitHub Enterprise, 자체 관리 GitLab 또는 기타 호스트: 먼저 pull/<number>/head를 시도한 다음 merge-requests/<number>/head를 시도

​

gitignored 파일을 worktree로 복사

.env
.env.local
config/secrets.json

​

worktree 이름 재사용

• 커밋되지 않은 변경 사항이나 추적되지 않은 파일이 없습니다.
• 여전히 Claude Code가 생성한 브랜치에 있습니다.
• 자체 커밋이 없거나 풀 요청 또는 병합 요청이 병합되고 원격 브랜치가 삭제되었습니다.

• Worktree가 조건 중 하나라도 실패합니다.
• Claude Code가 worktree의 상태를 확인할 수 없습니다.
• worktree.baseRef가 "head"입니다.
• 이름이 풀 요청 또는 병합 요청 참조입니다.

​

worktree 생성을 훅으로 대체

​

worktree가 메인 체크아웃과 공유하는 것

• 저장소의 .git 디렉토리: worktree의 git 명령은 메인 저장소의 공유 .git 디렉토리에 쓰며, 샌드박싱은 이러한 쓰기를 허용하므로 git commit과 같은 명령이 샌드박스가 활성화된 worktree 내부에서 작동합니다.
• 플러그인: 프로젝트 범위에서 메인 체크아웃에서 설치된 플러그인도 동일한 저장소의 worktree에 로드되므로 worktree마다 다시 설치할 필요가 없습니다. Claude Code v2.1.200 이상이 필요합니다.
• 권한 승인: worktree 세션에서 Bash 명령에 대해 “예, 다시 묻지 않기”를 선택하면 규칙이 메인 체크아웃의 .claude/settings.local.json에 저장되므로 메인 체크아웃과 저장소의 다른 모든 worktree에 적용되며, worktree 제거 후에도 유지됩니다. Windows 및 Claude Code가 저장소 루트를 사용하지 않는 다른 경우에는 규칙이 해당 worktree와 함께 유지됩니다. v2.1.211 이전에는 worktree에서 부여된 승인이 해당 worktree 내부에 저장되었으며, 다른 곳에 적용되지 않았고, worktree 제거 시 손실되었습니다. 승인이 저장되는 위치를 참조합니다.
• 추적되지 않은 skills, agents, 및 commands: worktree 체크아웃에 루트에 .claude/skills 디렉토리가 없을 때(예: .claude/skills가 gitignored인 경우), Claude Code는 메인 체크아웃의 프로젝트 skills를 worktree 세션에 로드합니다. 자체 .claude/skills 디렉토리가 있는 worktree에서는 해당 복사본만 로드됩니다. 동일한 읽기 통과는 .claude/agents 및 .claude/commands를 포함합니다. Skills의 경우 읽기 통과에는 Claude Code v2.1.277 이상이 필요합니다.

​

worktree 수동 관리

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

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

cd ../project-feature-a
claude

git worktree list

git worktree remove ../project-feature-a

​

비git 버전 관리

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

​

문제 해결

​

Claude Code가 시작 시 worktree에 진입할 수 없음

​

Symlink 경로에서 Worktree 생성 실패

​

Git LFS 파일이 Claude Code가 생성한 worktree의 포인터 파일임

• 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 설정의 includeIf는 이를 트리거하지 않습니다.
• Git was not run: the repository's own git config sets <key>: 메시지는 Git LFS를 실행할 프로그램으로 가리키는 키를 명시합니다. 예를 들어 lfs.customtransfer.<name>.path 또는 lfs.standalonetransferagent입니다. 해당 설정이 귀하의 것이면 전역 git 설정으로 이동하십시오. 인식하지 못하면 저장소의 git 설정에서 제거하십시오. 신뢰하지 않는 도구나 체크아웃이 작성했을 수 있기 때문입니다. 저장소의 설정에서 키가 없어지면 다시 시도하십시오.

​

Claude Code가 worktree 사용을 거부함

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

​

세션이 worktree 외부에서 재개됨

• Error: cannot resume into worktree <path>: ...This session was not started. 표가 Did not re-enter로 표시하는 거부의 경우입니다. Claude Code는 종료 전에 worktree 바인딩을 지우며, 오류는 이를 말합니다. 다음에 대화를 재개할 때, 세션은 worktree 격리 없이 현재 디렉토리에서 계속됩니다. v2.1.260 이전에는 Claude Code가 지워진 바인딩을 작성하지 않았으므로 동일한 재개의 모든 재시도가 동일한 오류로 실패했습니다. 기록 쓰기를 억제하면, 지우기를 저장할 수 없습니다. 오류는 동일한 명령이 다시 거부될 것이라고 말합니다. --fork-session과 worktree 없이 계속하는 방법으로 새 대화를 시작하는 것을 명시합니다.
• 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... 사라진 worktree의 경우입니다. Claude Code는 이를 출력하고 대화형 재개처럼 세션을 계속합니다.

​

참고 항목

• 서브에이전트: 세션 내의 격리된 에이전트에 작업 위임
• 크로스 세션 메시징: worktree의 세션이 서로 발견 사항을 전달하도록 허용
• 에이전트 팀: 여러 Claude 세션을 자동으로 조정
• 세션 관리: 대화 이름 지정, 재개 및 전환
• 데스크톱 병렬 세션: 데스크톱 앱의 worktree 기반 세션