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

​

worktree에서 Claude 시작

claude --worktree feature-auth

​

worktree 환경 설정

​

Claude에게 worktree 생성 요청

​

worktree 정리

• Worktree가 깨끗함: 이름 없는 세션의 경우 Claude는 worktree와 해당 브랜치를 자동으로 제거합니다. 이름이 지정된 세션은 나중을 위해 worktree를 유지할 수 있도록 먼저 프롬프트를 표시합니다.
• Worktree에 작업이 있음: Claude는 worktree를 유지하거나 제거할지 묻습니다. 유지하면 디렉토리와 브랜치가 보존됩니다. 나중에 돌아오려면 Claude Code가 종료 시 출력하는 claude --worktree <name> --resume 명령을 실행합니다. 제거하면 worktree 디렉토리와 해당 브랜치가 삭제되며, 그 안의 모든 작업도 함께 삭제됩니다
• 다른 브랜치가 체크아웃되어 있음: worktree가 자체 브랜치가 아닌 다른 브랜치에 있고 그 브랜치에 worktree의 시작 커밋 이후의 커밋이 있는 경우, Claude는 worktree를 유지하거나 제거할지 묻습니다. 어느 쪽을 선택하든 해당 다른 브랜치와 그 커밋은 유지됩니다. 제거하면 worktree 디렉토리와 worktree 자체의 브랜치, 즉 Claude가 worktree와 함께 생성한 브랜치가 삭제됩니다
• Worktree의 상태를 확인할 수 없음: Claude Code가 worktree의 변경 사항을 계산할 수 없거나 서브모듈 체크아웃을 검사할 수 없을 때, worktree를 자동으로 제거하지 않고 프롬프트를 표시합니다. 프롬프트는 확인할 수 없었던 항목을 명시합니다.

​

worktree 세션 재개

• 실행 디렉토리: 메인 체크아웃 또는 저장소의 다른 디렉토리에서 --resume으로 재개합니다. 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 잠금 및 수동 제거

​

worktree 생성 사용자 정의

​

기본 브랜치 선택

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

• 저장소를 지난 24시간 동안 페치하지 않았으면 기본 브랜치를 페치하며, 5초로 제한되고 페치가 실패하면 로컬로 캐시된 ref를 사용합니다.
• 페치는 터미널에서 입력을 기다리지 않습니다. git 또는 ssh가 비밀번호, 키 암호 또는 새 SSH 호스트 확인을 요청하는 경우에도 실패한 것으로 간주됩니다.
• 원격이 구성되지 않았거나 origin/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마다 다시 설치할 필요가 없습니다.
• 권한 승인: worktree 세션에서 Bash 명령에 대해 “예, 다시 묻지 않기”를 선택하면 규칙이 메인 체크아웃의 .claude/settings.local.json에 저장됩니다. 이 규칙은 메인 체크아웃과 저장소의 다른 모든 worktree에 적용되며, worktree 제거 후에도 유지됩니다. Windows 및 Claude Code가 저장소 루트를 사용하지 않는 다른 경우에는 규칙이 해당 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가 시작 시 워크트리에 진입할 수 없음

​

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

​

Claude Code가 생성한 워크트리에 대체된 객체의 원본 내용이 있음

​

Claude Code가 생성한 워크트리에서 Git LFS 파일이 포인터 파일임

• 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>: 메시지에는 lfs.customtransfer.<name>.path 또는 lfs.standalonetransferagent처럼 Git LFS가 실행할 프로그램을 가리키는 키가 명시됩니다. 해당 설정이 사용자가 지정한 것이라면 전역 git 구성으로 옮기십시오. 알지 못하는 설정이라면 신뢰할 수 없는 도구나 체크아웃이 기록했을 수 있으므로 저장소의 git 구성에서 제거하십시오. 저장소 구성에서 키가 제거되면 재시도하십시오.

​

부분 클론에서 워크트리 생성 실패

​

Can only use --worktree in a git repository

• 버전 관리가 없는 폴더에서는 그곳에서 git init을 실행하고 첫 커밋을 생성한 후 재시도하십시오.
• 다른 버전 관리 시스템의 체크아웃에서는 메시지가 제안하는 훅을 설정하십시오.
• 디렉터리에서 직접 작업하려면 --worktree 없이 Claude를 시작하십시오.

​

워크트리 디렉터리가 belongs to a different repository로 표시됨

​

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

• 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 거부 등 메인 체크아웃을 복구한 후 재시도하십시오. v2.1.302 이전에는 git 2.56 이상에서 the protected checkout 뒤의 <path>에 불필요한 .git 파일이 있을 때도 could not be resolved 끝맺음이 나타났습니다. 여기서 불필요하다는 것은 해당 파일의 gitdir: 줄에 있는 경로가 유효한 git 저장소로 이어지지 않는다는 의미입니다. 복구하려면 Claude Code를 업데이트하고 재시도하십시오. 해당 gitdir: 경로가 더 이상 존재하지 않으면 .git 파일을 삭제하고 재시도할 수도 있습니다.
• its recorded path has a network spelling이 포함된 경우: Claude Code는 네트워크 경로에 있는 워크트리로는 절대 재개하지 않습니다. 로컬 경로에 워크트리를 다시 생성하십시오.
• 그 밖의 끝맺음: 메시지에 core.worktree 리디렉션 제거나 워크트리 재생성 등 문제와 해결 방법이 명시되어 있으므로 이를 따르십시오. 메시지에 git ID를 확인할 수 없다고 표시된 디렉터리를 삭제하기 전에, 워크트리 경로의 심볼릭 링크나 git 자체의 실행 실��� 등 명시된 원인을 먼저 해결하십시오. 디렉터리가 정상일 수 있기 때문입니다. 다시 생성하는 경우, 이전 디렉터리는 디스크에 남아 있으므로 필요한 변경 사항을 먼저 복구하십시오.

​

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

• 표에서 Did not re-enter로 표시된 거부의 경우 Error: cannot resume into worktree <path>: ...This session was not started.가 표시됩니다. Claude Code는 종료하기 전에 워크트리 바인딩을 해제하며 오류에 그 사실이 표시됩니다. 다음에 대화를 재개하면 세션은 워크트리 격리 없이 현재 디렉터리에서 계속됩니다. v2.1.260 이전에는 Claude Code가 해제된 바인딩을 기록하지 않았기 때문에 같은 재개를 재시도할 때마다 동일한 오류로 실패했습니다. 트랜스크립트 쓰기를 억제한 경우에는 해제 내용을 저장할 수 없습니다. 이 경우 오류에는 같은 명령이 다시 거부될 것이라는 내용과 함께, 워크트리 없이 계속하는 방법으로 --fork-session과 새 대화 시작이 안내됩니다.
• Could not verify의 경우 Error: could not verify worktree <path> for this resume, so the resume was aborted...가 표시됩니다.
• Could not re-enter의 경우 Error: ...The worktree binding is kept.가 표시됩니다.
• 사라진 워크트리의 경우 Notice: the worktree <path> for this session no longer exists...가 표시됩니다. Claude Code는 이를 출력하고 대화형 재개와 마찬가지로 세션을 계속합니다.

​

참고 항목

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