TinyAgentDeck
worktree란?
git worktree는 하나의 저장소를 '다른 폴더 + 다른 브랜치'로 동시에 여는 git 기능입니다. 평소 작업 폴더는 그대로 두고, 그 옆에 독립된 작업 공간을 하나 더 만들 수 있습니다.
TinyAgentDeck에서 세션을 시작할 때 '독립 worktree로 생성' 토글을 ON으로 하면, 그 세션 전용 작업 폴더와 전용 브랜치 tad/session-<세션ID>가 자동으로 만들어지고 거기서 claude가 실행됩니다. 덕분에 같은 저장소에서 여러 에이전트를 동시에 돌려도 파일이 충돌하지 않습니다.
같은 저장소에서 둘 이상의 세션을 병렬로 돌릴 때 ON으로 합니다. 다른 프로젝트나 일회성 작업이라면 OFF(프로젝트 폴더에서 바로 실행)로 충분합니다.
worktree로 세션 시작하기
프로젝트 대시보드의 '세션 시작'에서 '독립 worktree로 생성'을 ON으로 하면, TinyAgentDeck이 뒤에서 다음을 처리합니다.
- worktree를 앱 관리 폴더(
~/Library/Application Support/…/worktrees/아래)에 생성 — 저장소 주변을 어지럽히지 않습니다 - 전용 브랜치
tad/session-<세션ID>를 만듭니다 - 그 worktree 폴더를 현재 위치로 하여
claude를 실행합니다
평소 작업 폴더(main을 체크아웃하고 있는 쪽)는 전혀 건드리지 않습니다. worktree는 끝나면 접을 수 있는 '격리된 병렬 작업 공간'입니다.
작업이 끝나면
worktree 안에서 한 변경은 그 세션의 브랜치 위에만 있을 뿐, 아직 main에도 평소 작업 폴더에도 들어가지 않았습니다. 그래서 정리하기 전에 '가져오는' 것이 핵심입니다.
커밋하지 않은 변경은 worktree를 삭제하면 사라집니다. 배포 스크립트로 이미 운영에 반영했더라도 git 이력에는 남지 않습니다. 다음에 main에서 운영으로 반영할 때 변경이 되돌아갈 위험이 있습니다.
그래서 순서는 언제나 커밋 → main에 병합 → 정리입니다.
가장 쉬운 방법 — Claude에게 맡기기
worktree 세션의 터미널에는 평소의 Claude Code가 있습니다. git 명령을 직접 입력할 필요가 없습니다. 작업이 끝나면 그대로 한국어로 부탁하면 됩니다.
예시(그대로 붙여 쓸 수 있습니다).
이 worktree의 변경을 전부 커밋하고 main 브랜치에 병합해 줘.
.env.local 같은 비밀 정보가 든 파일은 커밋하지 마.
병합이 끝나면 알려 줘.Claude가 하는 일(당신은 보고만 있으면 됩니다).
git status로 변경을 확인하고.gitignore와 대조해 비밀 정보를 제외- 의미 있는 메시지로 커밋
- worktree의 브랜치를 main 체크아웃으로 가져옴
- 병합되었다고 보고(충돌이나 미커밋이 있으면 알려 줌)
보고가 오면 ① 커밋되었는지 ② main에 병합되었는지 ③ 비밀 정보(.env.local 등)가 제외되었는지 세 가지만 확인합니다. 문제없다면 당신이 할 일은 카드를 닫는 것뿐입니다. 커밋이 끝나 변경이 남아 있지 않으므로 TinyAgentDeck이 worktree를 자동으로 삭제하고, 남은 tad/session-… 브랜치도 '고아 worktree' 섹션에서 한 번에 지울 수 있습니다.
worktree 안의 Claude는 자신이 지금 있는 worktree나 체크아웃 중인 브랜치 자체는 삭제할 수 없습니다(git이 '사용 중'이라며 거부합니다). 그래서 물리적인 정리는 앱의 몫입니다. Claude의 역할은 '커밋 → 병합 → 보고'까지. 그다음은 카드를 닫기만 하면 끝납니다.
매번 부탁하기 싫다 — 세션을 시작할 때 '최초 지시'에 '작업이 끝나면 커밋하고 main에 병합해 줘'라고 적어 두면 마지막에 자동으로 해 줍니다.
GitHub에도 남기고 싶다 — 부탁 문구에 '병합되면 git push origin main도 해 줘'를 더합니다. main에 병합해도 원격에는 아직 push되지 않으므로, 백업이나 이력 공유를 위해 남기려면 붙여 주세요(운영이 이미 배포되어 있다면 push 없이도 사이트는 동작합니다).
PR로 운영한다 — main에 직접 넣지 않고 '커밋하고 push, PR을 만들어 줘'라고 부탁하면 Claude가 그렇게 합니다.
직접 하고 싶을 때 — 수동 명령
안에서 무슨 일이 일어나는지 알고 싶거나, 손으로 확인하며 진행하고 싶다면 다음 3단계입니다. Claude에게 맡긴다면 건너뛰어도 됩니다.
worktree 안에서 커밋하기
작업한 세션의 터미널에서 실행합니다.
git status # 무엇이 바뀌었는지 확인(비밀 정보가 섞이지 않았는지 본다)
git add -A
git commit -m "알기 쉬운 메시지"
git branch --show-current # → tad/session-… 을 메모(다음에 사용)main에 병합하기
평소 작업 폴더(worktree가 아닌, main을 체크아웃하고 있는 쪽)의 터미널에서, 1단계에서 메모한 브랜치 이름을 병합합니다.
git merge tad/session-…운영에 이미 같은 내용이 나가 있어도, 이후 배포 스크립트를 다시 실행해도 결과는 바뀌지 않습니다(멱등). 이로써 main과 운영이 일치합니다.
worktree 정리하기
TinyAgentDeck의 카드를 닫기만 하면 됩니다. 1단계에서 커밋이 끝나 변경이 남아 있지 않으므로 앱이 자동으로 worktree를 삭제합니다.
남은 tad/session-… 브랜치는 2단계에서 병합되어 더 이상 필요 없습니다. 프로젝트 대시보드의 '고아 worktree' 섹션에서 '브랜치도 삭제'를 선택하거나, 수동으로 지울 수 있습니다.
git branch -d tad/session-… # 병합된 브랜치를 삭제비밀 정보를 커밋하지 않기
.env.local이나 API 키·시크릿이 든 파일은 절대 커밋하지 않습니다. .gitignore에 들어 있으면 git status에 나오지 않습니다(나온다면 git add하지 마세요).
worktree 쪽에만 적은 환경 변수는 main 쪽 폴더에는 존재하지 않습니다. 로컬에서 동작을 확인할 때만 main 쪽 .env.local에도 같은 값을 더해 주세요. 운영용 시크릿은 Cloudflare 등의 환경 변수로 따로 관리되므로 이 작업의 영향을 받지 않습니다.
커밋하지 않고 버리고 싶을 때
'이미 운영에 나가 있고, 코드도 이력도 필요 없다'는 드문 경우에는, 커밋하지 않고 카드를 닫은 뒤 확인 대화상자에서 강제 삭제를 선택하면 운영은 그대로 동작합니다. 다만 변경이 git에 전혀 남지 않으므로 기본적으로 권장하지 않습니다.
고아 worktree 정리
앱 밖에서 만들어졌거나 어떤 이유로 남아 버린 worktree는 '고아 worktree'로 프로젝트 대시보드에 나열됩니다. 여기서 삭제할 수 있고, '브랜치도 삭제'를 ON으로 하면 worktree를 지운 뒤 브랜치도 삭제합니다(되돌릴 수 없는 작업이므로 확인이 뜹니다).
자주 묻는 질문
커밋이나 main 병합도 Claude에게 시켜도 괜찮나요?
네. 그게 가장 쉬운 방법입니다. worktree 세션의 터미널에 위 부탁 문구를 그대로 붙여 넣으세요. 비밀 정보 제외까지 Claude가 판단해 결과를 보고합니다. 평소 git을 Claude에게 맡기던 분은 달라질 게 없습니다.
worktree를 지우면 브랜치도 지워지나요?
아니요. worktree 삭제와 브랜치 삭제는 별개입니다. 병합되었다면 git branch -d <이름>, 병합되지 않은 것을 강제로 지우려면 git branch -D <이름>.
main에 병합하는 걸 잊고 정리해 버렸어요.
커밋되어 있다면 브랜치는 남아 있으므로 언제든 git merge tad/session-…로 가져올 수 있습니다. 브랜치 이름은 worktree 폴더 이름(세션 ID)에서 tad/session-<세션ID> 형태로 정해집니다.
브랜치 이름을 모르겠어요.
worktree 터미널에서 git branch --show-current, 또는 저장소에서 git worktree list / git branch --list 'tad/session-*'로 확인할 수 있습니다.