메인 콘텐츠로 건너뛰기
git worktree는 자체 파일과 브랜치를 가진 별도의 작업 디렉토리이며, 메인 체크아웃과 동일한 저장소 히스토리 및 원격을 공유합니다. 각 Claude Code 세션을 자체 worktree에서 실행하면 한 세션의 편집이 다른 세션의 파일을 건드리지 않으므로, Claude가 한 터미널에서 기능을 구축하는 동안 두 번째 터미널에서 버그를 수정할 수 있습니다. 이 페이지는 CLI의 worktree 격리를 다룹니다. 아래의 모든 내용은 git 저장소를 가정합니다. 다른 버전 관리 시스템의 경우 비git 버전 관리를 참조하세요. 데스크톱 앱은 모든 새 세션에 대해 자동으로 worktree를 생성합니다. Worktree는 Claude를 병렬로 실행하는 여러 방법 중 하나입니다. 이들은 파일 편집을 격리하는 반면, 서브에이전트와 에이전트 팀은 작업 자체를 조정합니다. Claude를 병렬로 실행을 참조하여 접근 방식을 비교하거나, worktree로 서브에이전트 격리로 건너뛰어 worktree와 서브에이전트를 함께 사용합니다.

​
worktree에서 Claude 시작

--worktree 또는 -w를 전달하여 격리된 worktree를 생성하고 Claude를 시작합니다. 기본적으로 worktree는 저장소 루트의 .claude/worktrees/<value>/ 아래에 생성되며, worktree-<value>라는 새 브랜치에 생성됩니다: 
claude --worktree feature-auth
worktree를 다른 곳에 배치하려면 WorktreeCreate 훅을 구성하세요. 다른 터미널에서 다른 이름으로 명령을 다시 실행하여 두 번째 격리된 세션을 시작합니다: 
claude --worktree bugfix-123
이름을 생략하면 Claude가 bright-running-fox와 같은 이름을 생성합니다: 
claude --worktree
세션 중에 Claude에게 “worktree에서 작업하기”를 요청할 수도 있으며, EnterWorktree 도구로 하나를 생성합니다. worktree에 들어가면 Claude는 .claude/worktrees/ 아래의 다른 worktree로 EnterWorktree를 호출하여 직접 전환할 수 있습니다. 이전 worktree는 디스크에 그대로 남아 있습니다. 처음으로 디렉터리에서 --worktree를 사용하기 전에 해당 디렉터리에서 claude를 한 번 실행하여 작업 공간 신뢰 대화를 수락합니다. 신뢰가 아직 수락되지 않았으면 --worktree는 오류와 함께 종료되고 먼저 디렉터리에서 claude를 실행하도록 요청합니다. -p를 사용한 비대화형 실행은 신뢰 확인을 건너뛰므로 claude -p --worktree는 이를 수행하지 않고 진행됩니다.
.claude/worktrees/를 .gitignore에 추가하여 worktree 내용이 메인 체크아웃에서 추적되지 않은 파일로 나타나지 않도록 합니다.

​
기본 브랜치 선택

Worktree는 저장소의 기본 브랜치인 origin/HEAD에서 분기되므로 원격과 일치하는 깨끗한 트리에서 시작합니다. 원격이 구성되지 않았거나 페치가 실패하면 worktree는 현재 로컬 HEAD로 폴백합니다. 대신 항상 로컬 HEAD에서 분기하려면 설정에서 worktree.baseRef를 "head"로 설정합니다. baseRef를 "head"로 설정하면 새 worktree가 푸시되지 않은 커밋과 기능 브랜치 상태를 유지하므로, 진행 중인 작업에서 작동해야 하는 서브에이전트를 격리할 때 유용합니다. 설정은 "fresh" 또는 "head"만 허용하며, 임의의 git ref는 허용하지 않습니다: 
{
  "worktree": {
    "baseRef": "head"
  }
}
특정 풀 요청에서 분기하려면 #이 앞에 붙은 PR 번호 또는 전체 GitHub 풀 요청 URL을 전달합니다. Claude Code는 origin에서 pull/<number>/head를 페치하고 .claude/worktrees/pr-<number>에서 worktree를 생성합니다: 
claude --worktree "#1234"
worktree 생성 방식을 완전히 제어하려면 WorktreeCreate 훅을 구성하여 기본 git worktree 로직을 완전히 대체합니다.

​
gitignored 파일을 worktree로 복사

Worktree는 새로운 체크아웃이므로 메인 저장소의 .env 또는 .env.local과 같은 추적되지 않은 파일이 없습니다. Claude가 worktree를 생성할 때 자동으로 복사하려면 프로젝트 루트에 .worktreeinclude 파일을 추가합니다. 파일은 .gitignore 구문을 사용합니다. 패턴과 일치하고 gitignored된 파일만 복사되므로 추적된 파일은 절대 중복되지 않습니다. 이 .worktreeinclude는 두 개의 env 파일과 시크릿 구성을 각 새 worktree로 복사합니다:
.worktreeinclude
.env
.env.local
config/secrets.json
이는 --worktree로 생성된 worktree, 서브에이전트 worktree 및 데스크톱 앱의 병렬 세션에 적용됩니다.

​
worktree로 서브에이전트 격리

서브에이전트는 자체 worktree에서 실행될 수 있으므로 병렬 편집이 충돌하지 않습니다. Claude에게 “에이전트에 worktree 사용”을 요청하거나, 사용자 정의 서브에이전트에서 frontmatter에 isolation: worktree를 추가하여 영구적으로 설정합니다. 각 서브에이전트는 서브에이전트가 변경 없이 완료되면 자동으로 제거되는 임시 worktree를 가져옵니다. 서브에이전트 worktree는 --worktree와 동일한 기본 분기를 사용하므로, worktree.baseRef가 "head"로 설정되지 않은 한 저장소의 기본 분기에서 분기합니다.

​
worktree 정리

worktree 세션을 종료할 때 정리는 변경 사항을 만들었는지 여부에 따라 달라집니다:
  • 커밋되지 않은 변경 사항 없음, 추적되지 않은 파일 없음, 새로운 커밋 없음: worktree와 해당 브랜치가 자동으로 제거됩니다. 세션에 이름이 있으면 Claude는 대신 프롬프트를 표시하여 나중을 위해 worktree를 유지할 수 있습니다
  • 커밋되지 않은 변경 사항, 추적되지 않은 파일 또는 새로운 커밋 존재: Claude는 worktree를 유지하거나 제거할지 묻습니다. 유지하면 디렉토리와 브랜치가 보존되어 나중에 돌아올 수 있습니다. 제거하면 worktree 디렉토리와 해당 브랜치가 삭제되어 커밋되지 않은 모든 변경 사항, 추적되지 않은 파일 및 커밋이 버려집니다
  • 비대화형 실행: --worktree와 함께 -p로 생성된 worktree는 종료 프롬프트가 없으므로 자동으로 정리되지 않습니다. git worktree remove로 제거합니다
Claude가 서브에이전트 및 백그라운드 세션을 위해 생성한 worktree는 cleanupPeriodDays 설정보다 오래되면 자동으로 제거되며, 커밋되지 않은 변경 사항, 추적되지 않은 파일 및 푸시되지 않은 커밋이 없는 경우입니다. --worktree로 생성한 worktree는 이 스윕으로 절대 제거되지 않습니다. 에이전트가 실행 중인 동안 Claude는 해당 worktree에서 git worktree lock을 실행하여 동시 정리가 이를 제거할 수 없도록 합니다. 에이전트가 완료되면 잠금이 해제됩니다. 스윕이 유지하는 worktree를 정리하려면 git worktree remove를 실행하고, worktree에 커밋되지 않은 변경 사항이나 추적되지 않은 파일이 있으면 --force를 추가합니다.

​
worktree 수동 관리

worktree 위치 및 브랜치 구성을 완전히 제어하려면 Git으로 직접 worktree를 생성합니다. 이는 특정 기존 브랜치를 체크아웃하거나 worktree를 저장소 외부에 배치해야 할 때 유용합니다. 새 브랜치에서 worktree 생성: 
git worktree add ../project-feature-a -b feature-a
기존 브랜치에서 worktree 생성: 
git worktree add ../project-bugfix bugfix-123
worktree에서 Claude 시작: 
cd ../project-feature-a && claude
worktree 나열: 
git worktree list
완료되면 제거: 
git worktree remove ../project-feature-a
전체 명령 참조는 Git worktree 문서를 참조하세요. 각 새 worktree에서 개발 환경을 초기화하는 것을 잊지 마세요: 종속성 설치, 가상 환경 설정 또는 프로젝트의 설정이 필요한 모든 작업을 실행합니다.

​
비git 버전 관리

Worktree 격리는 기본적으로 git을 사용합니다. SVN, Perforce, Mercurial 또는 기타 시스템의 경우 WorktreeCreate 및 WorktreeRemove 훅을 구성하여 사용자 정의 생성 및 정리 로직을 제공합니다. 훅이 기본 git 동작을 대체하므로 --worktree를 사용할 때 .worktreeinclude가 처리되지 않습니다. 훅 스크립트 내에서 대신 로컬 구성 파일을 복사합니다. 이 WorktreeCreate 훅은 stdin에서 worktree 이름을 읽고, 새로운 SVN 작업 복사본을 체크아웃하고, Claude Code가 세션의 작업 디렉토리로 사용할 수 있도록 디렉토리 경로를 인쇄합니다: 
{
  "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 훅과 쌍을 이룹니다. 입력 스키마 및 제거 예제는 훅 참조를 참조하세요.

​
참고 항목

Worktree는 파일 격리를 처리합니다. 아래의 관련 페이지는 이러한 격리된 체크아웃으로 작업을 위임하고 생성한 세션 간에 전환하는 것을 다룹니다: