클로드 코드 여러 개 동시 실행: 워크트리와 에이전트 뷰

터미널 창을 두 개 열고 각각 claude를 실행하면 Claude Code(클로드 코드)가 두 개 돌아가긴 합니다. 문제는 둘이 같은 폴더를 보고 있다는 것입니다. 한쪽이 파일을 고치는 동안 다른 쪽이 같은 파일을 고치면 나중에 저장한 쪽이 앞의 작업을 덮어씁니다.

그래서 폴더를 갈라야 합니다. 명령어 한 줄이면 됩니다.

claude --worktree feature-auth

이 한 줄이 별도 폴더와 별도 브랜치를 만들고 거기서 Claude Code를 띄웁니다. 다른 터미널에서 이름만 바꿔 다시 실행하면 두 번째 세션이 생깁니다. 둘은 같은 저장소를 공유하지만 파일은 서로 안 건드립니다.

다만 여러 개를 돌리는 방법이 하나가 아니라 네 가지입니다. 이름이 비슷해서 헷갈리는데 쓰임이 전혀 다릅니다. 이 글은 그 넷을 먼저 갈라 놓고, 실제로 띄우는 절차와 여러 개를 돌릴 때 실제로 깨지는 것들까지 다룹니다.

이 글의 명령은 터미널 기준입니다. 데스크톱 앱의 Code 탭에서 Claude Code를 시작했더라도, 여기 나오는 명령은 앱 입력창이 아니라 터미널을 열어 실행합니다. 이 글은 2026년 9월, Claude Code 2.1.271 기준입니다.

git worktree

git worktree(깃 워크트리)란 같은 저장소를 여러 폴더에서 동시에 열어 두는 기능입니다. 저장소 기록과 원격 주소는 공유하면서 작업 폴더와 브랜치만 따로 갖습니다.

방법 네 가지: 파일, 화면, 맥락, 저장소

같은 "여러 개"인데 나누는 대상이 다릅니다.

가장 많이 헷갈리는 건 워크트리와 서브에이전트입니다. 워크트리는 창이 여러 개라 창마다 사람이 봐 줘야 합니다. 서브에이전트는 창이 하나고 그 안에서 일을 떼어 맡깁니다. 조사를 시켜 놓고 결과만 받고 싶으면 서브에이전트가 맞고, 두 가지 일을 진짜로 동시에 진행하려면 워크트리가 맞습니다. 서브에이전트 쪽은 별도 글에서 다뤘습니다.

아래는 워크트리와 에이전트 뷰를 다룹니다.

스텝 1: 워크트리로 두 번째 세션 띄우기

첫 실행이라면 그 폴더에서 claude를 한 번 그냥 실행해 신뢰 확인 창을 넘겨야 합니다. 이걸 안 해 두면 --worktree가 오류를 내고 종료합니다.

그다음 이름을 붙여 실행합니다.

claude --worktree feature-auth

다른 터미널에서 다른 이름으로 한 번 더 실행하면 두 번째 세션입니다.

claude --worktree bugfix-123

이름을 생략하면 bright-running-fox 같은 이름이 자동으로 붙습니다.

폴더는 어디에 생기나: 저장소 안의 .claude/worktrees/<이름>/입니다. 브랜치 이름은 worktree-<이름>이 됩니다.

이렇게 보이면 성공: 두 터미널의 Claude Code가 서로 다른 폴더를 작업 폴더로 잡고 있고, 한쪽에서 파일을 고쳐도 다른 쪽 화면에는 안 뜹니다.

.gitignore에 .claude/worktrees/를 넣어 두세요. 안 그러면 워크트리 안의 파일이 원래 폴더에서 "추적되지 않은 파일" 무더기로 보입니다.

node_modules와 .env는 따라오지 않습니다

워크트리는 완전히 새로운 체크아웃입니다. git이 추적하는 파일은 그대로 오지만, 설치해서 만든 node_modules나 .env처럼 git이 무시하는 파일은 따라오지 않습니다. 이 상태로 바로 npm run dev를 돌리면 모듈을 못 찾는다는 오류가 나거나, 환경 변수가 빠져 화면 일부가 조용히 깨집니다.

들어가서 평소 하던 설치를 한 번 더 해 주세요.

cd .claude/worktrees/feature-auth
npm install

.env처럼 매번 복사하기 번거로운 파일은 저장소 루트에 .worktreeinclude 파일을 만들어 두면 새 워크트리를 만들 때마다 자동으로 따라옵니다.

.env
.env.local

node_modules는 워크트리 수만큼 그대로 곱해집니다. 프로젝트 하나당 수백 메가바이트씩이라 워크트리를 서너 개 띄워 두고 오래 쓴다면 디스크 용량도 한 번씩 확인하는 편이 좋습니다.

시작 지점: 원격 기본 브랜치

기본은 원격의 기본 브랜치입니다. 즉 아직 푸시하지 않은 내 작업은 새 워크트리에 안 들어옵니다. 깨끗한 상태에서 시작하라는 뜻입니다.

지금 작업하던 상태를 그대로 물려받고 싶으면 설정을 바꿉니다.

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

"fresh"와 "head" 둘만 됩니다. 특정 커밋을 지정할 수는 없습니다.

특정 풀 리퀘스트에서 갈라져 나오려면 번호를 넘깁니다.

claude --worktree "#1234"

스텝 2: 에이전트 뷰로 한 화면에서 보기

창을 여러 개 띄우면 어느 세션이 나를 기다리는지 알기 어렵습니다. 하나씩 눌러 봐야 합니다.

claude agents

이 화면이 모든 백그라운드 세션을 상태별로 묶어 보여 줍니다. 나를 기다리는 것이 맨 위에 오고 작업 중인 것과 끝난 것이 그 아래로 묶입니다.

• 화살표로 줄을 고르고 Space를 누르면 그 세션이 뭘 묻고 있는지 엿봅니다. 여기서 바로 답할 수 있습니다
• Enter나 →를 누르면 그 세션으로 완전히 들어갑니다
• 빈 입력창에서 ←를 누르면 다시 목록으로 나옵니다
• Esc로 나가도 세션은 계속 돕니다

이미 열어 둔 세션을 이 목록에 넣으려면 그 세션 안에서 /bg를 실행하거나 빈 입력창에서 ←를 누릅니다.

이 기능은 아직 연구 미리보기입니다. 화면과 단축키가 계속 바뀔 수 있고, 오래된 버전에는 아예 없을 수 있습니다. claude --version으로 최신인지 확인하시면 됩니다.

워크트리마다 터미널을 자동으로 나누기

터미널 창을 손으로 배치하는 게 번거로우면 옵션이 하나 더 있습니다. tmux(티먹스)는 터미널 하나를 여러 칸으로 나눠 쓰게 해 주는 도구입니다.

claude --worktree feature-auth --tmux

워크트리를 만들면서 tmux 세션까지 같이 만듭니다. iTerm2를 쓰면 iTerm2의 화면 분할을 쓰고, 전통적인 tmux 화면을 원하면 --tmux=classic을 붙입니다. --worktree 없이는 못 씁니다.

동시에 돌리면 실제로 깨지는 것들

명령어는 한 줄인데, 두세 개를 실제로 굴려 보면 문서에 안 나오는 문제가 따로 생깁니다. 다섯 가지가 자주 걸립니다.

포트 충돌: 워크트리마다 다른 번호

가장 사람을 헷갈리게 하는 문제입니다. 워크트리 A에서 개발 서버를 3000번으로 띄워 두고, 워크트리 B에서도 3000번으로 띄우려 하면 B는 조용히 실패하거나 다른 포트로 밀립니다. 그런데 브라우저에서 3000번을 열면 A의 화면이 뜹니다.

여기서 무슨 일이 생기냐면, B에서 파일을 고치고 새로 고쳐도 화면이 안 바뀝니다. 캐시 문제로 착각하고 한참을 헤매게 됩니다.

포트를 워크트리마다 미리 정해 두세요. 3000, 3001, 3002처럼 고정해 두고 각 워크트리의 메모에 적어 둡니다.

그리고 응답 코드만 보고 판단하면 안 됩니다. 200이 떠도 남의 서버가 답한 것일 수 있습니다. 방금 고친 문장이 실제로 들어 있는지를 보는 편이 확실합니다.

curl -s http://localhost:3001/경로 | grep -c '방금 고친 문장 일부'

병합 충돌: 격리는 작업 중에만

파일이 격리된다는 건 작업하는 동안의 이야기입니다. 합칠 때는 결국 한 곳에서 만납니다. 두 워크트리가 같은 파일을 각자 고쳐 놨으면 그때 충돌이 납니다.

작업을 나눌 때 폴더 단위로 갈라 두면 대부분 사라집니다. 한쪽은 화면 코드, 다른 쪽은 문서와 콘텐츠처럼 나누는 식입니다. 어느 폴더를 누가 맡는지 정해 두지 않고 "이 기능", "저 기능"으로만 나누면 결국 같은 파일에서 만납니다.

스태시 공유 범위: 저장소 단위

git stash는 워크트리마다 따로가 아니라 저장소 하나에 하나입니다. A에서 stash를 쌓아 둔 상태로 B에서 git stash pop을 하면 A가 넣어 둔 것이 튀어나옵니다.

여러 개를 굴릴 때는 이름 없는 git stash는 쓰지 마세요. 잠깐 치워 둘 일이 있으면 임시 커밋을 만드는 편이 안전합니다.

사용량: 나눠 쓰는 게 아니라 합산

세션을 늘려도 사용 한도가 늘지는 않습니다. 한 계정의 한도를 모든 세션이 같이 씁니다. 에이전트 뷰에서 여러 개를 한 번에 띄우면 그만큼 빨리 소진됩니다.

공식 문서도 이 점을 명시하고 있습니다. 세션 하나하나가 같은 한도를 각자 소모하므로 많이 띄우기 전에 제한을 확인하라고 안내합니다.

같은 브랜치 금지: 격리가 사라지는 조건

앞에서 워크트리가 파일을 격리한다고 했는데, 정확히는 브랜치 단위로 격리합니다. 워크트리 두 개가 같은 브랜치를 물고 있으면 격리가 없습니다.

다행히 git이 기본적으로 이걸 막아 줍니다. 이미 다른 워크트리가 체크아웃한 브랜치를 또 다른 워크트리에 붙이려 하면 git이 거부합니다. claude --worktree로 정상적으로 띄우는 한 이름마다 별도 브랜치(worktree-<이름>)가 생기므로 이 상황 자체가 잘 일어나지 않습니다. 실제로 문제가 되는 건 git worktree add --force로 안전장치를 강제로 뚫거나, 워크트리 없이 같은 브랜치를 저장소 두 벌로 각자 내려받아 작업할 때입니다. 이게 가장 조용히 손해를 입히는 경우입니다.

공유 문서를 떠올리시면 쉽습니다. 두 사람이 같은 문서를 각자 자기 컴퓨터로 내려받아 고친 다음 각자 올리면, 나중에 올린 사람의 파일이 앞사람 것을 통째로 덮어씁니다. 앞사람이 고친 내용은 흔적도 없이 사라지고, 사라졌다는 사실조차 아무도 모릅니다. 같은 브랜치에 두 세션을 붙이면 이 일이 그대로 일어납니다.

충돌이라도 나면 차라리 낫습니다. 충돌은 눈에 보이고 멈춰 세워 주니까요. 덮어쓰기는 아무 경고 없이 지나갑니다.

세션 하나에 브랜치 하나를 지키세요. 그리고 여러 사람이나 여러 세션이 한 저장소를 쓴다면, 지금 누가 어느 파일을 잡고 있는지 미리 나눠 두는 편이 안전합니다.

워크트리 정리하기

세션을 끝낼 때 정리는 자동으로 되기도 하고 물어보기도 합니다. 이름을 붙였는지와 고친 게 남아 있는지로 갈립니다.

• 이름 없이 띄운 세션(자동으로 bright-running-fox 같은 이름이 붙은 경우)은 고친 것도 새 커밋도 없으면 워크트리와 브랜치가 알아서 사라집니다
• feature-auth처럼 이름을 직접 붙인 세션은 깨끗해도 남길지 먼저 물어봅니다. 나중에 다시 쓸 수 있게 하려는 것입니다
• 고친 게 남아 있으면 이름 여부와 상관없이 남길지 지울지 물어봅니다. 지우기를 고르면 커밋 안 한 변경과 새 파일이 같이 사라집니다. 여기서 한 번 더 생각하세요

남긴 워크트리를 나중에 지우려면 git 명령을 씁니다.

git worktree remove ../project-feature-a

커밋 안 한 것이나 새 파일이 남아 있으면 거부당합니다. 그래도 지우려면 --force를 붙입니다.

폴더만 삭제하면 안 됩니다. git 쪽에 등록이 남아 나중에 같은 이름을 다시 쓸 때 걸립니다.

문제 해결: 워크트리와 에이전트 뷰