클로드 코드 worktree 사용법: claude -w 로 같은 저장소에서 일 두 개 같이 하기

이 글 순서

1. worktree 가 뭔가요
2. 한국에서, 무슨 요금제
3. 처음이라면: 준비물
4. 처음이라면: claude -w
5. 만들어지는 자리와 이름
6. 끝낼 때 남는 것
7. 손으로 보고 지우기
8. 익숙해졌다면: 이어 하기
9. 대화 중에 옮겨 가기
10. .env 가 없을 때
11. 데스크톱 앱에서는
12. 더 깊이: 서브에이전트
13. 시작점 바꾸기와 PR
14. 같이 쓰는 것과 막는 것
15. 언제 쓰면 좋나
16. 막힐 때
17. 코덱스·제미나이 CLI 는
18. 다시 확인할 날짜
19. 참고한 자료

클로드 코드에게 보고서 폴더의 엑셀 합치기를 시켜 두고, 기다리는 동안 다른 터미널에서 같은 폴더의 그래프 고치기를 또 시켰다고 해 볼게요. 두 클로드가 같은 파일을 동시에 열어 고치면 한쪽이 고친 줄을 다른 쪽이 모르고 덮어쓸 수 있어요. worktree 는 이럴 때 쓰는 깃(git) 기능이에요. 같은 저장소를 폴더 하나 더 꺼내 놓고, 클로드 하나에 폴더 하나씩 나눠 주는 거예요. 같은 원고를 복사해 두 사람에게 한 부씩 주고 각자 고치게 한 뒤, 다 고친 쪽만 원본에 합치는 것과 비슷해요.

이 글은 클로드 코드 공식 문서 “worktree 를 사용하여 병렬 세션 실행”, “일반적인 워크플로”, “서브에이전트”, “설정 참조”, “데스크톱”과 git 공식 문서 git-worktree 를 2026년 10월 10일에 한국어 문서와 영어 문서로 같이 읽고 옮긴 거예요. 캡처는 클로드 코드 한국어 문서로 했어요. 비교하려고 OpenAI 코덱스 문서 Worktrees·Developer commands, 제미나이 CLI 문서 Git Worktrees, 안티그래비티 문서 Projects·CLI reference 도 같은 날 읽었어요. 터미널 그림은 이 PC 의 따로 만든 연습 저장소에서 돌린 git 명령만 옮겼고, 클로드 코드로 worktree 를 실제로 만들어 보지는 않았어요(로그인 없이 시험하는 폴더라서요).

worktree 가 뭔가요

단어부터 풀게요. 깃은 파일이 바뀐 기록을 남기는 프로그램이고, 깃으로 기록을 남기는 폴더를 저장소라고 해요. 커밋은 지금 파일 상태를 기록 하나로 저장하는 것, 브랜치는 그 기록을 따로 쌓아 가는 줄기예요. 터미널은 글자로 명령을 치는 검은 창이에요(윈도우는 PowerShell).

보통 저장소에는 폴더가 하나뿐이라서 한 번에 브랜치 하나만 펼쳐 놓을 수 있어요. 다른 브랜치를 보려면 지금 브랜치를 접고 바꿔 끼워야 해요. git 공식 문서는 worktree 를 “같은 저장소에 붙은 작업 폴더를 여러 개 두어, 브랜치를 한 번에 둘 이상 펼쳐 놓는 기능”이라고 설명해요. 처음 만든 폴더를 메인 worktree, 더 꺼낸 폴더를 linked worktree 라고 불러요.

• 따로인 것: 폴더 안 파일, 펼쳐 놓은 브랜치. 한쪽 폴더에서 고친 파일은 다른 폴더에 보이지 않아요.
• 같이 쓰는 것: 커밋·브랜치 기록(.git 폴더)과 원격(깃허브 같은 서버). 한쪽에서 커밋하면 다른 폴더에서도 그 커밋이 보여요.
• 깃의 규칙 하나: 브랜치 하나는 한 폴더에서만 펼칠 수 있어요. 그래서 worktree 마다 새 브랜치를 하나씩 만들어 줘요.

클로드 코드 문서는 여기에 클로드를 얹어 “세션마다 편집할 파일의 별도 사본이 주어지므로, 한 세션이 기능을 만드는 동안 두 번째 세션이 버그를 고칠 수 있다”고 적었어요. 세션은 클로드 코드를 켜서 끌 때까지 이어지는 대화 한 판이에요.

한국에서, 무슨 요금제

질문	답
한국에서 되나	됨(Anthropic 지원 국가에 South Korea)
클로드 코드 요금제	Pro·Max·Team·Enterprise, Console API
worktree 기능	문서에 요금제 조건 없음
꼭 있어야 하는 것	깃, 커밋이 하나 이상인 저장소

출처: anthropic.com 지원 국가 목록, 클로드 코드 문서 worktrees·common-workflows. 10월 10일 확인. worktree 는 내 PC 에서 깃이 폴더를 하나 더 만드는 일이라 요금제 조건이 따로 적혀 있지 않아요. 다만 세션을 둘 돌리면 주고받는 말도 두 배라서, 두 세션 모두 내 요금제 한도에서 빠져요. 아직 클로드 코드를 깔지 않았다면 클로드 코드 설치 윈도우 초보용부터 보고 오세요.

처음이라면: 준비물

1. 깃: 윈도우는 Git for Windows 를 깔아요. 터미널에서 git --version 을 쳐서 버전 숫자가 나오면 있는 거예요.
2. 깃 저장소인 폴더: 아직 아니라면 그 폴더에서 git init 으로 저장소를 만들어요.
3. 커밋 하나 이상: worktree 는 이미 있는 커밋에서 브랜치를 꺼내는 거라서, 커밋이 하나도 없으면 Failed to resolve base branch “HEAD”: git rev-parse failed 오류로 멈춰요(일반적인 워크플로 문서).
4. 그 폴더에서 claude 를 한 번: 처음 여는 폴더면 “이 폴더를 믿을까요” 창(작업 공간 신뢰)이 떠요. 이걸 먼저 받아 두지 않으면 claude -w 가 오류를 내고 끝나요.

저장소 만들기와 첫 커밋이 처음이라면 클로드 코드 깃 커밋·PR 맡기는 법에서 연습 폴더를 저장소로 만드는 순서를 먼저 따라 해 보세요. 클로드에게 “첫 커밋 해 줘”라고 시켜도 돼요.

처음이라면: claude -w

준비가 됐으면 명령 한 줄이에요.

cd C:\Users\사용자이름\보고서
claude --worktree graph

첫 줄은 저장소 폴더로 옮겨 가는 명령, 둘째 줄이 worktree 를 만들고 그 안에서 클로드 코드를 켜는 명령이에요. --worktree 는 -w 로 줄여 써도 같아요. 이름은 영어·숫자·하이픈으로 짧게 주는 게 무난해요(문서 예는 feature-auth). 한글 이름이 되는지는 문서에 없어서 이 글의 예도 영어로 적었어요.

일을 하나 더 맡기려면 터미널을 하나 더 열고, 같은 폴더에서 이름만 바꿔 다시 쳐요.

cd C:\Users\사용자이름\보고서
claude -w excel-merge

이제 터미널 두 개에서 클로드 두 개가 각자 다른 폴더를 고쳐요. 원래 폴더(보고서)는 손대지 않은 채 남아서, 그동안 내가 평소처럼 파일을 열어 봐도 돼요. 이름을 아예 빼고 claude -w 만 치면 클로드가 bright-running-fox 같은 이름을 지어 줘요.

한 가지만 기억하세요. 복사본 폴더에서 고친 것은 커밋하고 원래 브랜치에 병합하기 전까지 원래 폴더에 보이지 않아요. “고쳤다는데 왜 파일이 그대로지?” 싶으면 지금 원래 폴더를 보고 있는 거예요.

만들어지는 자리와 이름

무엇	claude -w graph 일 때
복사본 폴더	보고서\.claude\worktrees\graph\
새 브랜치 이름	worktree-graph
어디서 갈라지나	원격의 기본 브랜치(보통 main)
따라오는 파일	깃이 기록하는 파일만

출처: 클로드 코드 문서 worktrees. 10월 10일 확인. 셋째·넷째 줄이 처음 쓰는 분이 가장 놀라는 곳이에요.

• 시작점은 원격의 기본 브랜치: 기본값(fresh)은 깃허브 같은 원격의 기본 브랜치에서 갈라요. 하루 넘게 원격을 받아 오지 않았으면 5초까지만 받아 오고, 원격이 없는 저장소면 지금 내 브랜치(HEAD)에서 갈라요. 그래서 원래 폴더에서 아직 커밋하지 않은 변경 사항이나 원격에 올리지 않은 커밋은 복사본에 없을 수 있어요. 바꾸는 법은 아래 “시작점 바꾸기”에 있어요.
• 무시 파일은 안 따라옴: 복사본은 깃이 기록하는 파일로만 새로 꺼낸 폴더예요. .gitignore(깃이 무시할 파일 목록)에 든 .env, node_modules 같은 것은 없어요. 아래 “.env 가 없을 때” 절을 보세요.

문서는 .claude/worktrees/ 를 .gitignore 에 넣으라고 권해요. 넣지 않으면 원래 폴더에서 git status 를 칠 때 복사본 폴더가 “새 파일”로 표시돼요. 아래 연습 그림의 ?? .claude/ 줄이 그거예요. .gitignore 파일 맨 아래에 이 한 줄을 더하면 돼요.

.claude/worktrees/

끝낼 때 남는 것

worktree 세션에서 /exit 로 나가면 클로드 코드가 복사본 폴더를 살펴보고, 지우면 사라질 것(고친 파일, 깃이 아직 모르는 새 파일, 새 커밋)이 있는지 봐요. 그 결과에 따라 이렇게 나뉘어요.

• 남기기를 고르면 복사본 폴더와 브랜치가 그대로 남고, 나갈 때 다시 들어오는 명령 claude --worktree 이름 --resume 을 화면에 출력해 줘요. 이 줄을 메모해 두세요.
• 지우기를 고르면 복사본 폴더와 브랜치가 지워지고, 그 안에서 고친 것도 같이 사라져요. 남기고 싶은 변경 사항은 지우기 전에 “커밋해 줘”라고 시켜 두세요.
• “이름 붙인 세션”은 문서가 세션 이름 붙이기(claude -n, /rename) 절로 이어 둔 말이에요. claude -w 에 준 worktree 이름만으로도 “이름 붙인 세션”이 되는지는 문서에 적혀 있지 않아요(미확인). 세션 이름은 클로드 코드 이전 대화 이어 하기에 있어요.

claude -p(화면 없이 한 번 시키고 답만 받는 방식)로 돌린 worktree 는 나갈 때 확인 창이 없어서 자동으로 지워지지 않아요. 만들 때 걸어 둔 잠금도 다음 세션의 정리가 풀어 줄 때까지 남아요. claude -p 는 클로드 코드 claude -p 사용법에 따로 있어요.

손으로 보고 지우기

남겨 둔 복사본이 쌓이면 git 명령으로 보고 지워요. 클로드 코드가 만든 worktree 도 깃 입장에서는 보통 worktree 라서 똑같이 다뤄져요. 이 PC 에 따로 만든 연습 저장소(장부.csv 파일 하나)에서 클로드 코드가 붙이는 형식 그대로 이름을 줘서 돌려 봤어요.

git worktree list

이 저장소에 붙은 폴더를 모두 보여 줘요. 줄마다 폴더 경로, 마지막 커밋 번호, 펼친 브랜치가 나와요. 맨 위가 원래 폴더예요. 그림은 Git Bash(Git for Windows 에 딸린 터미널) 화면이지만, 같은 git 명령을 PowerShell 에서 쳐도 똑같이 돼요.

그림 아래쪽은 이미 원래 폴더에 펼쳐 둔 main 브랜치를 다른 폴더에 또 펼치려다 거절당한 모습이에요. 위에서 말한 “브랜치 하나는 한 폴더에서만” 규칙이에요. 클로드 코드가 worktree 마다 worktree-이름 브랜치를 새로 만드는 이유이기도 해요.

git worktree remove .claude/worktrees/bugfix
git branch -d worktree-bugfix

첫 줄은 복사본 폴더를 지우고, 둘째 줄은 다 쓴 브랜치를 지워요. -d 는 이미 병합한 브랜치만 지워서 안전해요.

그림 가운데의 git -C 폴더 명령 은 “그 폴더로 cd 해서 명령을 치는 것”과 같은 뜻이에요. 복사본 폴더에서 커밋한 거예요. 복사본에 커밋하지 않은 변경 사항이 있으면 remove 가 그림처럼 멈춰요. 변경 사항이 필요 없다면 --force 를 붙여 지우고, 필요하면 커밋한 뒤 원래 폴더에서 git merge 로 병합해요. 그 밖에 이런 때가 있어요.

• 잠겨 있다며 거절: claude -p 로 만든 것이나 도는 중인 세션의 것이에요. 세션이 끝난 게 맞으면 git worktree unlock 경로 뒤에 remove.
• 탐색기로 폴더를 그냥 지웠다면: 깃 쪽 기록만 남아요. git worktree prune 이 남은 기록을 치워요(git 문서).
• 합치지 않은 브랜치를 버릴 때: git branch -D 브랜치이름. 대문자 D 는 합치지 않은 커밋도 지우니 한 번 더 확인하세요.

익숙해졌다면: 이어 하기

남겨 둔 worktree 로 다음 날 돌아오는 길은 둘이에요.

claude --worktree graph --resume
claude -r

첫 줄은 나갈 때 화면에 출력해 준 바로 그 명령이에요. 이미 있는 이름을 다시 주면 새로 만들지 않고 그 폴더를 열어요. 둘째 줄처럼 원래 폴더에서 claude -r 로 지난 대화를 골라도, worktree 안에서 끝난 대화면 클로드 코드가 그 worktree 로 다시 들어가요. 대화 목록에서 Ctrl+W 를 누르면 저장소의 모든 worktree 대화를 같이 보여 줘요. 목록 쓰는 법은 이어 하기 글에 있어요.

같은 이름을 다시 줄 때 하나 알아 둘 게 있어요. 복사본에 고친 것도 자기 커밋도 없고 클로드가 만든 브랜치 그대로라면, 옛 위치에서 이어 가지 않고 기본 브랜치의 지금 상태로 새로 맞춰 열어요. 풀 요청이 병합되고 원격 브랜치가 지워진 경우도 같아요. 그 밖에는 옛 위치에서 그대로 열어요.

claude -w 로 만든 worktree 는 복사본 폴더 안에서 이어 열어도 클로드 코드가 알아보고 다시 들어가요. 다만 git worktree add 로 손으로 만든 worktree 를 그 안의 하위 폴더에서 이어 열면 “launch from the parent checkout” 같은 말과 함께 거절할 수 있으니, 그런 것은 원래 폴더(저장소 맨 위)에서 이어 여세요. 복사본 폴더를 지운 뒤 그 대화를 이어 열면 worktree 가 없다고 알리고 지금 폴더에서 그냥 이어 가요.

대화 중에 옮겨 가기

claude -w 로 켜지 않았어도, 하던 대화에서 “worktree 에서 작업해 줘”라고 하면 클로드가 EnterWorktree 라는 도구로 worktree 를 만들어 그쪽으로 옮겨 가요. 큰 수정을 시키기 직전에 “이건 따로 해 줘”라고 할 때 편해요. 끝나면 ExitWorktree 로 원래 폴더로 돌아와요.

.claude/worktrees/ 밖의 폴더로 옮겨 가려 하면 클로드 코드가 먼저 허락을 물어요. 작업 폴더와 쓰기 권한, CLAUDE.md 같은 설정이 통째로 그 위치로 옮겨 가기 때문이에요. 이 확인 창은 “다시 묻지 않기”나 권한 규칙으로 끌 수 없고 bypassPermissions 모드만 건너뛰어요(2.1.206 부터).

.env 가 없을 때

복사본 폴더에서 프로그램을 돌렸더니 “API 키가 없다”거나 “모듈을 못 찾는다”가 뜨면, 무시 파일이 안 따라와서예요. 문서가 알려 주는 방법은 셋이에요.

1. 준비 명령 다시 돌리기: 복사본은 새로 꺼낸 폴더라 npm install 같은 준비를 다시 해야 해요. 클로드에게 “의존성 깔아 줘”라고 시켜도 돼요.
2. .worktreeinclude 파일: 저장소 맨 위에 이 이름의 파일을 만들고 따라올 무시 파일을 적어 두면, 클로드 코드가 worktree 를 만들 때마다 복사해 줘요. 적는 형식은 .gitignore 와 같고, 무시 목록에 든 파일만 복사돼요.
3. 큰 폴더는 이어 붙이기: node_modules 처럼 큰 폴더는 설정의 worktree.symlinkDirectories 에 적으면 복사하지 않고 원래 폴더 것을 이어 붙여(심볼릭 링크) 써요.

.env
.env.local
config/secrets.json

.worktreeinclude 에 넣는 형식이에요(문서 예). 이 세 파일이 새 worktree 마다 복사돼요.

{
  "worktree": {
    "symlinkDirectories": ["node_modules"]
  }
}

.claude/settings.json 에 넣는 형식이에요. node_modules 를 worktree 마다 다시 깔지 않고 원래 폴더 것을 같이 써요.

.worktreeinclude 는 claude -w 만이 아니라 서브에이전트 worktree, 데스크톱 앱의 worktree 세션에도 똑같이 적용돼요.

데스크톱 앱에서는

클로드 데스크톱 앱의 코드 탭에서는 명령 대신 새 세션을 시작할 때 브랜치 이름 옆의 worktree 옵션을 골라요. 저장 위치 기본값도 같은 .claude/worktrees/ 이고, 설정의 Worktree location 에서 바꾸며 브랜치 이름 앞에 붙일 말(branch prefix)도 정할 수 있어요. 다 쓴 worktree 는 사이드바 세션의 보관 아이콘으로 지워요. 터미널 버전과 달리 앱은 처음부터 끝까지 버튼으로 다뤄요. 앱 쪽 순서와 화면은 클로드 코드 데스크톱 앱 코드 탭 쓰는 법에 있어요.

더 깊이: 서브에이전트

서브에이전트는 클로드가 일을 쪼개 맡기는 작은 보조 클로드예요. 기본은 내 폴더를 같이 고치는데, 여럿이 동시에 같은 파일을 고치면 충돌해요. 그래서 서브에이전트마다 임시 worktree 를 주는 방법이 있어요. 서브에이전트가 뭔지는 클로드 코드 서브에이전트 사용법에 있어요.

• 그때그때: “에이전트들은 worktree 를 써서 해 줘”라고 말로 시켜요.
• 늘: .claude/agents/ 의 서브에이전트 파일 프론트매터에 isolation: worktree 한 줄을 넣어요. 그 서브에이전트는 언제나 자기 worktree 에서 돌아요.

서브에이전트가 아무것도 고치지 않고 끝나면 그 worktree 는 자동으로 지워져요. 고친 게 있으면 남아 있다가, 주기적인 정리가 작업을 잃지 않고 지울 수 있을 때 지워요. 정리 기준 날짜는 설정 cleanupPeriodDays 를 따라요. 시작점은 claude -w 와 같은 기본 브랜치라서, 지금 하던 일 위에서 돌려야 하는 서브에이전트라면 아래 baseRef 를 “head” 로 바꿔요.

자기 worktree 의 서브에이전트는 지시 파일(CLAUDE.md 등)을 worktree 가 아니라 원래 대화에서 받아요. 기본 자리(.claude/worktrees/)라면 worktree 쪽 CLAUDE.md 와 .claude/rules/ 는 그 브랜치에서 내용이 달라도 읽지 않아요. 2.1.295(10월 8일) 에서는 자기 worktree 의 서브에이전트에게 원래 세션의 브랜치·상태가 보이던 문제를 고쳤어요. 백그라운드 세션이 worktree 로 옮겨 가는 규칙은 클로드 코드 agent view 사용법에 따로 있어요.

시작점 바꾸기와 PR

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

새 worktree 를 원격 기본 브랜치가 아니라 지금 내 브랜치(HEAD)에서 꺼내게 하는 설정이에요. 아직 올리지 않은 커밋까지 복사본에 들어가요.

값은 “fresh”(기본)와 “head” 둘뿐이고 브랜치 이름을 적을 수는 없어요. 이미 있는 특정 브랜치에서 시작하려면 깃으로 직접 만들고 그 폴더에서 claude 를 켜요.

git worktree add ../보고서-수정 고칠갈래
cd ../보고서-수정
claude

첫 줄은 이미 있는 고칠갈래를 저장소 옆 폴더(보고서-수정)에 펼쳐요. 이렇게 손으로 만든 worktree 는 클로드 코드가 자동으로 지우지 않으니 다 쓰면 git worktree remove 로 지워요.

풀 요청(PR, 내 변경 사항을 합쳐 달라는 요청)을 받아 살펴볼 때도 쓸 수 있어요. claude --worktree “#1234” 처럼 # 붙인 번호나 깃허브 풀 요청 주소, 깃랩 머지 요청 주소를 주면 그 변경 사항을 origin 에서 받아 .claude/worktrees/pr-1234 에 펼쳐요. # 은 셸이 주석으로 읽지 않게 꼭 따옴표로 감싸요. 받아 올 때 비밀번호를 묻는 저장소면 실패하니, 한 번 손으로 git fetch 를 해 두세요.

같이 쓰는 것과 막는 것

무엇	worktree 에서는
.git 기록	원래 저장소 것을 같이 씀
프로젝트 플러그인	다시 깔지 않아도 됨(2.1.200 부터)
“다시 묻지 않기” 허락	원래 폴더에 저장, 윈도우는 그 worktree 에만
무시된 스킬·에이전트	원래 폴더 것을 읽음

출처: 클로드 코드 문서 worktrees. 10월 10일 확인. 윈도우에서 쓰는 분은 셋째 줄을 기억하세요. 맥·리눅스에서는 worktree 에서 준 허락이 원래 폴더의 .claude/settings.local.json 에 저장돼 다른 worktree 에도 먹고 지운 뒤에도 남는데, 윈도우에서는 그 worktree 에만 남아요. worktree 를 지우면 허락도 같이 사라지니, 자주 쓰는 허락은 원래 폴더에서 주거나 설정 파일에 규칙으로 적어 두세요. 규칙 적는 법은 클로드 코드 권한 설정에 있어요.

worktree 안에서 도는 세션은 원래 폴더를 건드리지 못하게 클로드 코드가 네 가지를 막아요. 원래 폴더 파일을 고치는 Edit·Write, 원래 폴더에서 도는 명령, git -C 처럼 깃을 원래 폴더로 돌리는 명령, 글자만 보고 어디서 깃이 돌지 알 수 없는 명령이에요. 그 세션이 띄운 서브에이전트에도 똑같이 걸려요.

다만 빈틈이 있어요. 문서대로라면 이 검사는 명령이 어떤 파일을 쓰는지까지 따라가지 않아서, cp 나 셸의 > 로 원래 폴더에 파일을 쓰는 명령은 막지 않아요. 그리고 PowerShell 명령에는 넷 가운데 “명령이 도는 폴더” 검사 하나만 걸려요. 윈도우에서 PowerShell 로 쓴다면 worktree 를 완벽한 샌드박스로 믿지 말고, 권한 설정과 같이 쓰세요.

언제 쓰면 좋나

여기서부터는 공식 문서를 바탕으로 한 제 생각이에요.

이럴 때	worktree
같은 저장소에서 일 두 개를 동시에 맡길 때	쓰면 좋음
되돌리기 어려운 큰 수정을 시험할 때	쓰면 좋음
남의 풀 요청을 받아 돌려 볼 때	쓰면 좋음(“#번호”)
클로드 하나만 돌리고 내가 지켜볼 때	안 써도 됨
깃 저장소가 아닌 폴더	못 씀(서로 다른 파일을 맡기기)
설치에 오래 걸리는 큰 프로젝트	symlinkDirectories 부터

클로드 하나에 한 가지 일씩 시키는 분이라면 worktree 가 오히려 번거로워요. 원래 폴더에서 바로 고치고 /rewind 로 되돌리는 쪽이 쉬워요(compact·clear·rewind 차이). 터미널 두세 개를 띄워 놓고 일을 나눠 맡기기 시작하면 그때부터 worktree 가 값을 해요. 그때도 처음에는 claude -w 이름 과 끝날 때 확인 창, 이 두 가지만 알면 충분해요. 백그라운드로 여러 세션을 맡기고 한 화면에서 보는 쪽은 agent view, 한 세션 안에서 나눠 맡기는 쪽은 서브에이전트예요.

막힐 때

이런 말이 뜨면	이렇게
Failed to resolve base branch “HEAD”	커밋이 없음. 첫 커밋부터
작업 공간 신뢰를 먼저 하라는 오류	그 폴더에서 claude 를 한 번 켜서 받기
is already used by worktree	그 브랜치가 다른 폴더에 펼쳐져 있음. 다른 브랜치로
contains modified or untracked files	커밋하거나 --force
잠겨 있다며 remove 거절	git worktree unlock 뒤 다시
LFS 파일이 짧은 텍스트 파일로 보임	worktree 안에서 git lfs pull
Refusing to use … as an isolation worktree	원래 폴더에서 다시 켜기, 메시지 끝 안내대로
Failed to fetch PR/MR #번호	비밀번호 묻는 저장소. git fetch 를 손으로 한 번

출처: 클로드 코드 문서 worktrees·common-workflows, 이 PC 연습 저장소 출력(셋째·넷째 줄). 10월 10일 확인. LFS 는 큰 파일을 따로 두는 깃 확장인데, git lfs install --local 로 저장소 설정에 넣어 둔 경우 클로드 코드가 안전을 위해 그 설정을 건너뛰어서 생기는 일이에요.

윈도우에서 /exit 의 지우기를 골랐는데 폴더가 남는다면 버전부터 보세요. 2.1.286(9월 30일)에서 클로드 코드가 띄운 서버·셸을 먼저 멈춘 뒤 지우도록 바뀌었어요. 그 전에는 윈도우에서 도는 프로그램이 폴더를 붙잡아 지워지지 않을 수 있었어요. 또 2.1.205 전에는 worktree 안에 다른 곳을 가리키는 링크 폴더가 있으면 그 대상 폴더까지 지울 수 있었다고 문서에 적혀 있어요. claude --version 으로 버전을 보고 claude update 로 올려 두세요. 이 PC 는 2.1.292, 10월 10일 변경 기록의 맨 위는 2.1.295 였어요.

코덱스·제미나이 CLI 는

OpenAI 코덱스와 구글 제미나이 CLI·안티그래비티에도 worktree 가 있지만 놓인 자리가 달라요.

항목	클로드 코드	코덱스	제미나이 CLI
터미널에서 여는 법	claude -w 이름	CLI 명령 문서에 없음	gemini -w 이름
어디에서 쓰나	터미널·데스크톱 앱	챗GPT 데스크톱 앱 Worktree	터미널(실험 기능, 켜야 함)
저장 위치	.claude/worktrees/	$CODEX_HOME/worktrees	.gemini/worktrees/
브랜치	worktree-이름 새로	브랜치 없이(detached HEAD)	문서 안 설명이 서로 다름
끝낼 때	깨끗하면 지움, 아니면 물음	15개 넘거나 보관하면 지움	지우지 않음, 손으로
.env 따라오기	.worktreeinclude	.worktreeinclude	공식 안내 없음

출처: code.claude.com worktrees, learn.chatgpt.com 코덱스 Worktrees·Developer commands(CLI), geminicli.com Git Worktrees. 10월 10일 확인.

코덱스는 worktree 를 챗GPT 데스크톱 앱 쪽에 두었어요. 새 대화 화면 입력칸 아래에서 Worktree 를 고르고 시작 브랜치를 고르면, 브랜치 없이(detached HEAD) 복사본을 만들어요. 시작 브랜치에 커밋하지 않은 변경 사항이 있으면 그것도 복사본에 얹어 줘서 클로드 코드의 기본값과 반대예요. 다 하면 Hand off 로 대화와 변경 사항을 원래 폴더(Local)로 넘겨요. 최근 15개만 남기고 오래된 것부터 지우는데, 지우기 전에 작업을 떠 두었다가 그 대화를 다시 열면 복원하게 해 줘요. 터미널 버전 코덱스 CLI 의 명령·슬래시 명령 문서에는 worktree 가 없고, /worktree 는 IDE 확장 쪽 목록에 있어요. 코덱스 쓰는 법은 코덱스 CLI 사용법 처음부터에 있어요.

제미나이 CLI 는 클로드 코드와 가장 닮았어요. gemini --worktree 이름(-w)으로 .gemini/worktrees/ 에 복사본을 만들어요. 다만 아직 실험 기능이라 /settings 에서 Enable Git Worktrees 를 켜거나 settings.json 에 “experimental”: { “worktrees”: true } 를 넣어야 해요. 끝낼 때는 변경 사항을 지키려고 아무것도 지우지 않으니, 다 쓰면 git worktree remove 와 git branch -D 로 직접 치워야 해요. 브랜치 이름은 문서 위쪽에서 “넘긴 이름이 폴더 이름이자 브랜치 이름”이라고 하고, 아래 지우기 예에서는 worktree-feature-search 를 지워서 서로 맞지 않아요. 만든 뒤 git worktree list 로 실제 이름을 보고 지우세요.

항목	안티그래비티
여는 법	2.0 앱에서 New worktree mode 고르기
터미널(CLI)	CLI 참조에 worktree 옵션 없음
저장 위치	공식 안내 없음
끝낼 때	공식 안내 없음
.env 따라오기	공식 안내 없음

출처: antigravity.google Projects·CLI reference. 10월 10일 확인. 안티그래비티는 2.0 앱에서 대화를 시작할 때 Local mode(지금 폴더를 바로 고침)와 New worktree mode(대화마다 새 worktree) 가운데 고르는 방식이에요. 서브에이전트끼리 충돌하지 않게 하려면 New worktree mode 를 고르라고 문서가 적었어요. 셋을 다른 기능까지 한 표로 비교한 글은 클로드 코드·코덱스·제미나이 CLI 비교, 안티그래비티 CLI 는 안티그래비티 CLI 사용법 처음부터에 있어요.

다시 확인할 날짜

• 10월 24일: 클로드 코드 worktrees 문서(끝낼 때 규칙, 윈도우 권한 승인 저장 위치), 제미나이 CLI worktree 가 실험 기능 표시가 빠졌는지.
• 11월 10일: 코덱스 CLI 에 worktree 명령이 생겼는지, 안티그래비티 CLI 에 worktree 옵션이 생겼는지.

이 글의 내용은 2026년 10월 10일 공식 문서 기준이에요. 클로드 코드는 버전이 자주 올라가서 규칙과 메시지가 바뀔 수 있어요. 글과 다르게 보이면 공식 문서의 지금 내용을 먼저 보세요. 세 회사 요금제와 한도는 AI 비교 2026에 한 표로 모아 두었어요.

같이 보면 좋은 글: 클로드 코드 깃 커밋·PR 맡기는 법: 연습 폴더부터 /diff·push 막기·서명 줄까지

같이 보면 좋은 글: 클로드 코드 데스크톱 앱 코드 탭 쓰는 법: 터미널 없이 폴더 고르기부터 worktree 까지

같이 보면 좋은 글: 클로드 코드 서브에이전트 사용법: 컨텍스트 아끼기, 만드는 법, 모델 정하기

같이 보면 좋은 글: 클로드 코드 agent view 사용법: claude agents 로 백그라운드 세션 여러 개 맡기기, /bg·attach 까지

같이 보면 좋은 글: 클로드 코드 이전 대화 이어 하기: claude -c·-r·/resume 쓰는 법, 이름 붙이기와 30일 삭제

같이 보면 좋은 글: AI 비교 2026: 클로드·챗GPT·제미나이 요금제·한도·기능 표

같이 보면 좋은 글: 클로드 코드 클라우드 세션 사용법: PC 를 꺼도 도는 웹 세션, 깃허브 연결과 --teleport 가져오기

이 글이 들어간 총정리: 클로드 코드에 일 맡기는 법

같이 보면 좋은 글: 클로드 코드 /batch 사용법: 큰 수정을 5~30조각으로 나눠 동시에, 계획 확인부터 되돌리기까지

참고한 자료

2026년 10월 10일에 확인했어요.

• worktree 를 사용하여 병렬 세션 실행 (클로드 코드 공식 한국어 문서, --worktree·정리·이어 하기·격리 규칙·서브에이전트·기본 브랜치·PR·.worktreeinclude·공유하는 것·문제 해결)
• Run parallel sessions with worktrees (클로드 코드 공식 영어 문서, 버전 숫자 맞춰 보기)
• 일반적인 워크플로 (클로드 코드 공식 한국어 문서, 커밋이 없을 때 Failed to resolve base branch)
• Subagents (클로드 코드 공식 문서, isolation: worktree)
• Settings reference (클로드 코드 공식 문서, worktree.baseRef·symlinkDirectories·sparsePaths·bgIsolation)
• Desktop (클로드 코드 공식 문서, worktree 옵션·Worktree location·branch prefix)
• CLI reference (클로드 코드 공식 문서, -w·--worktree)
• Changelog (클로드 코드 공식 문서, 2.1.286·2.1.295)
• git-worktree (git 공식 문서, main·linked worktree, add·list·remove·prune·lock)
• Supported countries and regions (Anthropic, South Korea)
• Worktrees (OpenAI 코덱스 공식 문서, 데스크톱 앱 Worktree·Hand off·15개·.worktreeinclude)
• Developer commands (OpenAI 코덱스 공식 문서, CLI 명령·슬래시 명령 목록)
• Git Worktrees (제미나이 CLI 공식 문서, 실험 기능·--worktree·끝낼 때·지우는 법)
• Projects (안티그래비티 공식 문서, Local mode·New worktree mode)
• CLI reference (안티그래비티 공식 문서, 명령 옵션 목록)