AI 코딩 도구에 로그인 화면 수정과 목록의 페이지 넘김 오류 수정을 동시에 맡긴다고 하자. 두 세션이 같은 폴더를 열면 한쪽이 고친 파일을 다른 쪽이 다시 읽고 덮어쓸 수 있다. 어느 작업의 변경인지 가려내느라, 일을 나눠 맡긴 뒤의 검토가 더 번거로워진다. Worktrunk는 이때 작업마다 별도 폴더와 Git 브랜치를 만들고, 오가고, 정리하는 명령줄 도구다.
화면은 채팅창이나 웹 대시보드가 아니라 터미널이다. wt list를 실행하면 브랜치 이름, 수정 상태, 추가·삭제한 줄 수 등이 표로 나온다. 코드를 작성하는 주체는 별도로 실행한 Claude Code나 Codex 같은 에이전트다. Worktrunk가 관리하는 결과물은 로컬 폴더의 파일과 Git 변경 이력이며, 어떤 코드를 채택할지는 사람이 차이 화면인 diff를 읽고 결정한다.
브랜치만 나누는 것과 폴더까지 나누는 것은 어떻게 다른가
브랜치는 코드 이력의 갈래다. 한 폴더에서 브랜치를 바꾸면 그 폴더에 보이는 파일도 바뀐다. 두 에이전트를 동시에 실행할 때 필요한 것은 두 갈래의 이름만이 아니라, 각자가 계속 읽고 쓸 파일 공간이다. Git의 worktree는 하나의 저장소에 여러 작업 디렉터리를 연결해 서로 다른 브랜치를 동시에 펼쳐 놓는 기능이다. Worktrunk는 이 Git 기능을 더 짧은 명령으로 다룬다.
이를 작은 Python 예제로 확인했다. 같은 파일 안에 로그인 입력 확인과 페이지 범위 계산 함수를 두고, login과 paging worktree에서 각각 다른 함수를 수정했다. 아래는 Worktrunk 0.78.0을 실행한 출력의 왼쪽 열이다. 두 작업에는 각각 한 줄 추가와 한 줄 삭제가 잡혔고, 원래 main 폴더의 파일은 그대로 남았다. 예제에서는 에이전트를 호출하지 않고 두 함수를 직접 수정했다.
현재 위치를 뜻하는 맨 왼쪽 @와 수정 상태를 뜻하는 !는 역할이 다르다. 표는 어디에 변경이 있는지 찾게 해 주지만, 변경이 올바른지까지 판정하지는 않는다. 예제에서도 폴더마다 별도로 검사를 실행했다. 로그인 쪽 두 검사, 페이지 계산 쪽 두 검사를 통과한 뒤 변경을 합치고 네 검사를 다시 실행했다.
두 작업을 맡길 때는 세션의 시작 폴더부터 고른다
공식 README에는 여러 Claude 세션을 서로 다른 worktree에서 실행하는 명령과, 터미널 화면을 탭으로 나누는 Zellij를 함께 쓰는 공개 데모가 있다. Zellij는 세션을 보여 주고, Worktrunk는 세션이 들어갈 작업 폴더를 관리한다.
Worktrunk와 Claude Code가 설치되고 셸 연동을 마쳤다면 다음처럼 두 터미널 탭에서 각각 시작할 수 있다. 명령은 로그인 입력 검증과 페이지 계산 오류를 나눠 맡기는 예시다. -c는 새 브랜치와 worktree를 만들고, -x claude는 이동한 곳에서 Claude를 실행한다. -- 뒤 문장은 Claude에 전달된다.
# 첫 번째 터미널 탭
wt switch -c -x claude login -- '빈 로그인 입력을 거부하고 테스트를 추가해 줘'
# 두 번째 터미널 탭
wt switch -c -x claude paging -- '첫 페이지 범위 계산을 고치고 테스트를 추가해 줘'작업 요청에는 바꿀 기능과 통과해야 할 조건을 함께 적는다. 예를 들어 페이지 계산은 첫 페이지와 다음 페이지에 어떤 항목이 나와야 하는지를 정한다. 에이전트가 끝났다는 답을 남기면 해당 폴더로 이동해 프로젝트의 테스트 명령을 실행하고, git diff로 아직 커밋하지 않은 변경을 읽는다. 이미 커밋한 작업은 git diff main...HEAD처럼 기준 브랜치와의 차이도 확인한다. 커밋되지 않은 변경과 커밋된 변경을 한쪽만 보고 놓치지 않도록 한다.
Worktrunk는 macOS·Linux·Windows용 설치 경로를 제공한다. Windows의 wt는 Windows Terminal 명령과 겹치므로 Winget 설치에서는 git-wt 이름을 쓸 수 있다. 폴더 이동까지 연결하려면 해당 명령의 config shell install로 셸 연동을 설정한다. 이미 에이전트가 worktree 생성과 세션 전환을 충분히 관리해 준다면, 같은 일을 위해 도구를 하나 더 넣을 필요는 없다.
폴더를 나눠도 데이터베이스와 권한은 따라 나뉘지 않는다
worktree는 컨테이너나 권한 샌드박스가 아니다. 파일을 나눠 두어도 두 개발 서버가 같은 포트를 쓰면 충돌하고, 같은 데이터베이스 주소를 쓰면 같은 데이터를 바꾼다. 두 세션이 같은 계정의 자격증명을 물려받는 문제도 남는다. 에이전트가 다른 폴더에 접근하지 못하게 막는 기능으로 생각해서는 안 된다.
공식 문서는 브랜치 이름을 포트 번호로 바꾸는 hash_port와 worktree별 데이터베이스를 만드는 설정 예제를 제공한다. 이는 자동으로 생기는 격리가 아니라 사용자가 추가하는 실행 설정이다. 포트 배정 뒤에는 다른 프로세스의 사용 여부도 확인해야 한다. .env 같은 설정 파일을 복사한다면 개발용 접속 대상과 키가 맞는지부터 확인한다.
반복 준비 작업은 hook으로 묶을 수 있다. hook은 생성·전환·병합 같은 시점에 실행하는 셸 명령이다. 예를 들어 의존성 설치가 끝나야 에이전트를 시작할 수 있다면 기다리는 pre-start에 두고, 개발 서버처럼 백그라운드에서 돌릴 일은 post-start에 둔다. 저장소의 .config/wt.toml에 들어 있는 프로젝트 명령은 처음 실행할 때 승인을 요구하며, 명령이 바뀌면 다시 승인한다. 낯선 저장소에서는 승인 전에 내용을 읽어야 한다. --yes는 그 질문을 생략하므로 편의 옵션처럼 무심코 붙이지 않는다.
합치는 명령은 검토를 마친 뒤에 실행한다
팀에서 GitHub의 풀 리퀘스트(PR)로 검토한다면 각 브랜치를 커밋하고 push한 뒤 PR을 연다. 원격 CI와 리뷰를 거쳐 합치고, 그다음 wt remove로 작업 공간을 정리한다. Worktrunk의 로컬 병합 명령이 팀의 리뷰 승인이나 브랜치 보호 규칙을 대신하는 것은 아니다.
혼자 관리하는 저장소 등에서 로컬로 합치기로 했다면 작업 브랜치 안에서 wt merge main을 실행한다. Git의 익숙한 git merge와 방향이 다르다. 현재 브랜치가 main을 가져오는 것이 아니라, 현재 브랜치의 작업을 로컬 main에 넣는다. 기본 흐름은 커밋을 하나로 묶고(squash), 대상 위로 이력을 재정렬한 뒤(rebase), 대상 브랜치를 앞으로 이동시키고 작업 공간을 정리하는 순서다.
이 명령은 기본 설정에서 아직 커밋하지 않은 파일까지 포함할 수 있다. 원치 않는 파일이 섞이지 않았는지 먼저 살펴보고, 검토용 폴더를 남기려면 --no-remove를 쓴다. pre-merge에 테스트를 설정하면 rebase 뒤, 실제 병합 전에 실행하며 실패 시 병합을 멈춘다. hook을 설정하지 않았거나 생략했다면 이 검사도 없다. 명령 자체는 원격의 최신 변경을 fetch하지 않으므로 원격 동기화와 최종 push도 별도로 관리한다.
두 작업이 각각 테스트를 통과해도 같은 동작을 다른 방향으로 고쳤다면 합친 결과는 다시 검사해야 한다. Worktrunk를 써서 줄어드는 일은 작업 폴더와 브랜치를 반복해서 만들고 찾아가는 수고다. 여러 변경을 잠시 따로 보관하고 하나씩 검토할 일이 잦을 때 잘 맞는다. 한 번의 질문에 답을 얻거나 한 작업만 차례로 처리한다면, 기존 폴더와 Git 명령으로도 충분하다.
출처: Worktrunk README와 공개 데모 · Hooks · Merge · Tips & Patterns