git worktree 관리자
Claude Code, Codex, 모든 에이전트 CLI를 위한
티켓에서 체크박스 하나를 켜거나 에이전트를 추가할 때 worktree를 고르면, 그 에이전트는 자기 브랜치 위의 자기 체크아웃에서 작업합니다. 여러 에이전트가 같은 저장소를 동시에 수정해도 서로의 파일을 건드리지 않습니다.
에이전트가 시작되기 전에 AgentsRoom이 의존성을 설치하고 .env 파일을 새 worktree에 복사하므로, 에이전트는 바로 빌드하고 테스트를 돌릴 수 있습니다. 작업이 끝나면 데스크톱에서든 휴대폰에서든 변경사항 탭에서 그 worktree를 리뷰하고, 커밋하고, 푸시하고, 병합하세요.
- 백엔드 에이전트.worktrees/fix-login-redirect준비됨
- 프런트엔드 에이전트.worktrees/settings-dark-mode작업 중
- QA 에이전트.worktrees/agents/qa리뷰
에이전트 세 개, worktree 세 개, 저장소 하나: 각 체크아웃은 에이전트가 시작되기 전에 준비되고, 따로따로 리뷰되고 병합됩니다.
같은 체크아웃에 에이전트 두 개를 두는 것은 두 사람이 같은 파일에 동시에 타이핑하는 것과 같습니다. 한쪽이 수정하는 도중에 다른 쪽이 포매터를 돌리고, 한쪽이 다른 쪽 발밑에서 브랜치를 바꾸며, 마지막에 리뷰하는 diff에는 두 작업이 뒤섞입니다. git worktree가 이 문제를 해결합니다. 같은 저장소의 두 번째 체크아웃으로, 자기 폴더와 자기 브랜치를 가지며 기록은 공유하지만 파일은 공유하지 않습니다.
worktree 하나를 만드는 데는 git 명령 하나면 됩니다. 어려운 것은 열 개를 관리하며 사는 일입니다. 새 worktree에는 node_modules도 .env도 없어서 에이전트의 첫 빌드가 실패하고, 어느 에이전트가 어디서 작업하는지 알려주는 것도 없으며, 작업이 끝나도 여전히 폴더를 찾아 리뷰하고, 커밋하고, 다시 병합해야 합니다.
AgentsRoom이 이 생명 주기를 맡습니다. 백로그 티켓이나 에이전트가 worktree를 요청하면, AgentsRoom은 최신 기준 브랜치에서 프로젝트 안 .worktrees/ 아래에 worktree를 만들고, 준비하고, 그 안에서 에이전트를 시작하며, 변경사항 탭에 선택기를 마련해 리뷰, 커밋, 푸시, 병합을 할 수 있게 합니다. 어떤 CLI가 에이전트를 돌리든 똑같이 동작합니다: Claude, Codex, GitHub Copilot CLI, Cursor 및 그 외 에이전트 CLI 10개.
worktree는 선택 사항입니다. worktree가 없는 에이전트는 예전처럼 프로젝트 폴더에서 계속 작업하고, 티켓마다, 에이전트마다, 에이전트 템플릿마다 사용 여부를 정할 수 있습니다.
worktree 관리자가 하는 일
작업이 격리된 체크아웃을 요청하는 순간부터 그 브랜치가 다시 병합되는 순간까지.
백로그 티켓마다 worktree 하나
티켓에서 '이 작업을 위해 별도 워크트리에서 코딩'을 체크하고, 프로젝트의 worktree 중 하나를 고르거나 새 브랜치 이름을 입력하세요. 티켓을 시작하면 worktree가 만들어지고 그 안에서 에이전트가 실행됩니다.
에이전트를 추가할 때 worktree 고르기
'에이전트 추가' 창의 '작업 공간' 카드에는 '메인', 프로젝트의 기존 worktree, '새로 만들기'가 표시됩니다. git worktree add로 직접 만든 worktree도 목록에 나옵니다.
템플릿의 에이전트마다 새 worktree
저장된 에이전트나 기본 프로필에서 '에이전트마다 새 worktree'를 켜면, 거기서 생성되는 에이전트마다 자기 브랜치를 갖습니다. 이름은 agents/<템플릿>, 그다음 -2, -3이므로 복사본끼리 체크아웃을 공유하는 일이 없습니다.
첫 실행부터 빌드 준비 완료
새 worktree에서 첫 에이전트가 시작되기 전에, AgentsRoom은 필요한 git 무시 파일(기본값은 모든 .env 파일)을 복사하고 lockfile에서 감지한 설치 명령을 실행합니다: yarn, pnpm, npm, bun, uv, poetry, pipenv, bundle, composer.
worktree마다 리뷰, 커밋, 푸시
변경사항 탭 상단의 '워크트리' 선택기가 diff, '검토', '커밋', '풀', '푸시'를 그 체크아웃으로 전환합니다. 자기 worktree를 가진 에이전트의 배지를 클릭하면 바로 그 worktree가 열립니다.
티켓이 완료되면 다시 병합
'작업 완료 시 현재 브랜치에 자동 병합'을 켜 두면, 티켓을 완료로 표시할 때 그 브랜치가 병합됩니다. '작업이 끝나면 자동으로 커밋'을 켜면 에이전트가 커밋하지 않고 남긴 작업도 병합에 포함됩니다.
동작 방식
티켓 하나가 양식에서 병합까지 거치는 과정.
- 1
티켓에서 worktree 요청하기
티켓 양식의 '실행' 아래에서 '이 작업을 위해 별도 워크트리에서 코딩'을 체크하세요. 칩에서 기존 worktree를 고르거나 '브랜치 이름' 필드를 그대로 두면 됩니다. 이 필드는 직접 수정하기 전까지 제목에서 미리 채워지며, 작업이 시작될 때 새 worktree가 됩니다.
- 2
티켓 시작하기
AgentsRoom은 기준 브랜치(원격의 기본 브랜치, 또는 프로젝트 설정에서 지정한 '워크트리 기준 브랜치')를 fetch하고, .worktrees/<branch>/ 아래에 worktree를 만든 뒤, 그 폴더를 클론의 .git/info/exclude에 추가합니다. 그래서 메인 체크아웃에서 추적되지 않는 파일로 나타나는 일이 없습니다.
- 3
worktree가 준비된 다음 에이전트가 시작됩니다
에이전트의 터미널에 설치 명령과 그 출력이 표시되고, 알림이 무시 파일을 몇 개 복사했는지 알려 준 뒤, 에이전트 CLI가 worktree 안에서 시작됩니다. 이 과정은 worktree마다 한 번만 일어납니다. 설치가 실패해도 에이전트를 막지 않으며, 오류는 그 터미널에 남습니다.
- 4
리뷰하고 병합하기
변경사항 탭에서 worktree를 골라 diff를 읽고 커밋하세요. 티켓을 완료로 표시하면, 자동 병합이 켜져 있을 때 그 브랜치가 현재 브랜치에 병합되고 확인 창에 결과가 표시됩니다. worktree 자체는 마지막으로 살펴볼 수 있도록 디스크에 남습니다.
Claude Code와 Codex도 이미 worktree를 만듭니다. 차이는 이렇습니다.
Claude Code에는 자체 플래그가 있습니다: claude --worktree feature-auth는 worktree-feature-auth라는 브랜치 위에 .claude/worktrees/feature-auth를 만들고, .worktreeinclude 파일에 나열된 git 무시 파일을 복사하며, 종료할 때 worktree를 유지할지 삭제할지 묻습니다. 문서에는 worktree가 새 체크아웃이며 의존성은 직접 설치하거나 Claude에게 맡겨야 한다고 분명히 적혀 있습니다. 서브에이전트도 isolation: worktree로 각자 worktree를 받을 수 있습니다.
Codex 앱은 $CODEX_HOME/worktrees에서 worktree를 관리하고, 고른 브랜치에서 detached HEAD 상태로 시작하며, 마찬가지로 .worktreeinclude를 읽고, 로컬 환경을 선택하면 그 설정 스크립트를 실행하며, 기본적으로 최근 15개를 유지합니다. Handoff는 채팅과 그 코드를 Local과 worktree 사이에서 옮깁니다. codex-cli 0.162.1에도 --worktree 플래그가 있습니다.
둘 다 잘 만들어졌고, 둘 다 한 업체에 속합니다. AgentsRoom은 이들을 대체하지 않습니다. 같은 격리를 한 단계 위, 즉 티켓과 에이전트가 있는 곳에서 모든 CLI에 한꺼번에 제공하고, 에이전트가 보기 전에 체크아웃을 준비하며, 리뷰, 커밋, 병합을 이미 쓰고 있는 창 안에 둡니다. 2026년 10월, Claude Code 2.1.299와 codex-cli 0.162.1에서 확인했습니다.
알아 둘 점
- worktree는 리뷰할 수 있도록 일부러 자동 삭제되지 않습니다. .worktrees/ 아래에 쌓이므로, 작업이 끝나면 git worktree remove로 삭제하세요. 에이전트가 아직 그 안에서 실행 중일 때는 절대 삭제하지 마세요.
- 자동 병합이 충돌을 만나면 경고를 기록하고, 티켓은 그대로 완료로 넘어갑니다: 그 병합은 직접 해결하세요.
- worktree를 쓰려면 프로젝트 루트에 git 저장소가 있어야 합니다. 여러 저장소를 나란히 모아 두기만 한 폴더에서는 쓸 수 없습니다: 각 저장소를 별도의 프로젝트로 여세요.
- SSH 서버에서 연 프로젝트는 worktree가 서버에 만들어지며, 설치 단계는 없습니다. 에이전트가 원격 호스트에서 실행되는 로컬 체크아웃은 worktree를 쓸 수 없고, 티켓은 시작하는 대신 그 사실을 알려 줍니다.
- QA 에이전트는 자기 worktree를 갖지 않습니다. 새 worktree에는 테스트해야 할 커밋되지 않은 작업이 들어 있지 않으므로, 마스터 에이전트의 체크아웃 안에서 테스트합니다.
자주 묻는 질문
git worktree란 무엇이고, 왜 AI 에이전트에게 하나씩 줘야 합니까?
git worktree는 같은 저장소의 두 번째 체크아웃으로, 자기 폴더와 자기 브랜치를 가지며 기록과 원격을 메인 체크아웃과 공유합니다. AI 코딩 에이전트마다 하나씩 주면 각 에이전트가 자기 파일 복사본을 수정하고, 빌드하고, 커밋하므로, 동시에 작업하는 두 에이전트가 서로의 작업을 덮어쓰거나 상대의 발밑에서 브랜치를 바꾸는 일이 없습니다. git 쪽 내용을 더 자세히 다룬 가이드는 블로그에 있습니다: git worktree: 여러 AI 에이전트를 충돌 없이 돌리기 위한 기반.
Claude Code에 worktree가 내장되어 있습니까?
네. claude --worktree <이름>(또는 -w)은 worktree-<이름>이라는 브랜치 위에 .claude/worktrees/<이름>을 만들고, .worktreeinclude에 나열된 git 무시 파일을 복사하며, 종료할 때 worktree를 유지할지 삭제할지 묻습니다. 서브에이전트는 isolation: worktree로 자기 worktree에서 실행될 수 있습니다. 의존성은 설치하지 않습니다. AgentsRoom에서는 이것을 계속 써도 되고, 티켓이나 에이전트가 worktree를 요청하게 해도 됩니다. 후자는 worktree를 준비하고 변경사항 탭에 표시까지 해 줍니다(Claude Code 2.1.299에서 확인).
Codex는 worktree를 지원합니까?
Codex 앱은 지원합니다: $CODEX_HOME/worktrees에 관리되는 worktree를 detached HEAD 상태로 만들고, .worktreeinclude에 나열된 무시 파일을 복사하며, 로컬 환경의 설정 스크립트를 실행할 수 있고, 최근 15개를 유지하며, Handoff로 채팅을 Local과 worktree 사이에서 옮깁니다. codex-cli 0.162.1에는 새 관리형 worktree에서 세션을 실행하는 --worktree 플래그가 있습니다. AgentsRoom은 다른 에이전트와 똑같은 방식으로, 티켓이나 '에이전트 추가' 창에서 Codex 에이전트에게 worktree를 줍니다.
AgentsRoom worktree에서는 어떤 에이전트 CLI를 실행할 수 있습니까?
전부입니다: worktree는 그저 에이전트의 작업 디렉터리일 뿐이므로, 거기서 어떤 CLI가 돌든 Claude, Codex, GitHub Copilot CLI, Cursor 및 그 외 에이전트 CLI 10개가 똑같이 동작합니다. Kimi Code와 Antigravity CLI는 정확한 경로로 폴더를 신뢰하므로, AgentsRoom은 실행 전에 새 worktree를 이들에게 신뢰된 폴더로 등록해 신뢰 확인 질문에서 멈추지 않게 합니다.
worktree마다 yarn install을 실행하고 .env를 복사해야 합니까?
아니요. 새 worktree에서 첫 에이전트가 시작되기 전에, AgentsRoom은 메인 체크아웃의 git 무시 파일 중 '이 체크아웃에서 복사할 파일'과 일치하는 것(기본값은 모든 .env 파일)을 복사하고, 루트의 lockfile에서 감지한 설치 명령을 실행합니다. 둘 다 '프로젝트 설정 > Git > 새 워크트리 준비'에서 설정하며, 여기서 명령을 예를 들어 pnpm install && pnpm build:deps로 바꿀 수 있습니다. worktree에 이미 있는 파일은 절대 덮어쓰지 않습니다.
에이전트가 worktree에서 한 작업을 어떻게 리뷰하고 병합합니까?
변경사항 탭을 열고 상단의 '워크트리' 선택기에서 worktree를 고르세요: 파일 목록, diff, '검토', '커밋', '풀', '푸시'가 그 체크아웃을 대상으로 동작합니다. 티켓의 경우 '작업 완료 시 현재 브랜치에 자동 병합'은 티켓을 완료로 표시할 때 그 브랜치를 병합하고, '작업이 끝나면 자동으로 커밋'(설정 > Backlog)은 에이전트가 남긴 작업을 먼저 커밋하므로 병합에 작업 전체가 담깁니다.
worktree는 어디에 있고, 정리됩니까?
프로젝트 안의 .worktrees/<branch>/ 아래에 있으며, 프로젝트 설정에서 '워크트리 기준 브랜치'를 지정하지 않았다면 원격의 기본 브랜치에서 만들어집니다. 이 폴더는 클론의 .git/info/exclude에 추가되고 .gitignore에는 절대 추가되지 않으므로 커밋에 들어가지 않습니다. worktree는 자동으로 삭제되지 않습니다: 다 쓰고 나면 git worktree remove로 삭제하세요.
휴대폰이나 원격 서버에서도 worktree를 쓸 수 있습니까?
둘 다 됩니다. 휴대폰에서는 변경사항 화면에 같은 '워크트리' 선택기가 있고, worktree를 요청한 티켓을 휴대폰에서 시작하면 다른 티켓처럼 데스크톱이 준비한 worktree 안에서 실행됩니다. SSH 서버에서 연 프로젝트는 worktree가 서버에 만들어지며, 설치 단계는 없습니다. 에이전트가 원격 호스트에서 실행되는 로컬 체크아웃은 worktree를 쓸 수 없고, 티켓은 시작하는 대신 그 사실을 알려 줍니다.
더 알아보기
git worktree: 여러 AI 에이전트를 충돌 없이 돌리기 위한 기반
병렬로 돌리면 에이전트들이 서로의 작업을 덮어씁니다. git worktree면 명령어 두 줄로 해결됩니다. 사용법을 알려드립니다.
에이전트 10개가 동시에 같은 타입 체크를 실행했습니다. 해결책은 디렉터리였습니다.
같은 체크아웃에 코딩 에이전트 17개, 동시에 도는 tsc 10개, load average 37에 남은 RAM 87 MB. 90초짜리 타입 체크가 7분 36이 걸렸습니다. 무엇을 측정했는지, 왜 머신이 계산을 하고 있지 않았는지, 그리고 문제를 해결한 작은 공유 잠금을 정리했습니다. 어떤 저장소에도 그대로 옮길 수 있습니다.
3에서 8개의 코딩 에이전트를 병렬로 실행하면서 추적을 잃지 않는 방법
여러 Claude Code 또는 Codex 에이전트를 한 번에 실행하는 것은 쉽습니다. 제어를 유지하는 것이 문제입니다. 실제로 효과가 있는 방법을 소개합니다.
이런 것도 함께 보세요
작업 관리
드래그 앤 드롭으로 AI 에이전트를 지휘하는 시각적 칸반 보드. TODO에 작업을 만들고 In Progress로 끌어다 놓으면 Claude 에이전트가 자동으로 생성되며, Pending과 Done 칼럼으로 진행 상황을 추적하세요. 병렬 AI 코딩을 위한 백로그 기반 개발.
에이전트별 리뷰
각 AI 에이전트의 코드 변경사항을 개별적으로 검토하세요. AgentsRoom은 어떤 Claude Code 에이전트가 어떤 파일을 수정했는지 추적합니다. 에이전트별로 diff를 필터링하고, 개별 검토하고, 깨끗한 git 히스토리를 위해 에이전트별로 커밋하세요.
다중 프로젝트 · 다중 에이전트 · 병렬
AgentsRoom은 AI 에이전트를 여러 프로젝트에 걸쳐 병렬로, 모두 하나의 창에서 실행합니다: Claude, Codex, GitHub Copilot CLI, Cursor 및 그 외 에이전트 CLI 10개. 색상으로 구분된 역할, 실시간 상태, 프로젝트별 카운터, 네이티브 데스크톱 및 모바일 알림. 12개의 터미널 탭과 iTerm2, Warp, tmux에 흩어진 Claude Code 세션의 혼란을 대신하는 시각적 대안입니다.
에이전트 사용자 정의
14개의 내장 에이전트 역할 중에서 선택하고, The Agency의 전문 에이전트를 추가하거나, 고유한 시스템 프롬프트를 가진 맞춤형 AI 코딩 에이전트를 구축하세요. 그런 다음 팀과 함께 에이전트를 공유하고, 커뮤니티에 게시하여 모두가 함께 발전할 수 있도록 하세요.
Multi-Agent Workflow • Handoff • Feedback Loop
AgentsRoom Agent Teams는 AI 코딩 에이전트를 진짜 엔지니어링 팀처럼 연결합니다. Dev, QA, PM, Security, DevOps 역할을 배선하는 비주얼 워크플로 에디터 (n8n 스타일 캔버스). 요약, git diff, 리스크, 테스트 힌트가 담긴 자동 핸드오프. 머신 검증 품질 게이트 (판정은 에이전트가 아니라 당신의 테스트 스위트가 합니다), 병렬 QA와 Security 리뷰 브랜치, 조건부 연결, 피드백 루프, 사이클 상한. 역할을 어떻게 돌릴지 팀마다 고릅니다. 역할에서 역할로 모핑하며 컨텍스트 전체를 지키는 에이전트 하나, 아니면 역할마다 살아 있는 에이전트를 두고 실시간으로 메시지를 주고받게 하는 방식입니다. Claude, Codex, GitHub Copilot CLI, Cursor 및 그 외 에이전트 CLI 10개에서 돌아가는 에이전트에게 없던 멀티 에이전트 오케스트레이터입니다.
모든 에이전트에게 자기 체크아웃을 주세요
macOS, Windows, Linux용 AgentsRoom을 다운로드하고, 여러 에이전트가 서로 방해하지 않고 같은 저장소에서 작업하게 하세요.
컴패니언 앱: 이동 중에도 에이전트를 모니터링
Claude, Codex, Antigravity CLI 또는 다른 AI 공급자를 사용하세요.
버그와 요청을 공개 백로그로 바로 보내세요.