Maximilian Roos가 만든 오픈소스 프로젝트(
max-sixty/worktrunk, MIT 또는 Apache-2.0).
왜 필요한가?
Claude Code나 Codex 같은 에이전트는 감독 없이도 긴 작업을 처리할 수 있어 여러 개를 동시에 돌리는 경우가 많습니다. git의 worktree 기능을 쓰면 에이전트마다 작업 디렉터리를 따로 주어 서로의 변경을 건드리지 않게 할 수 있습니다.
문제는 git worktree가 다루기 번거롭다는 점입니다. 새 worktree 하나를 시작하는 데도 git worktree add -b feat ../repo.feat 후 cd ../repo.feat처럼 브랜치 이름을 세 번 입력해야 합니다. Worktrunk는 worktree를 브랜치 이름으로 지정하고 경로는 템플릿으로 계산해, 이 과정을 명령 하나로 줄입니다.
핵심 명령
| 작업 | Worktrunk | git만 쓸 때 |
|---|---|---|
| worktree 전환 | wt switch feat | cd ../repo.feat |
| 만들고 Claude 실행 | wt switch -c -x claude feat | git worktree add -b feat ../repo.feat && cd ../repo.feat && claude |
| 정리 | wt remove | cd ../repo && git worktree remove ../repo.feat && git branch -d feat |
| 상태와 함께 목록 보기 | wt list | git worktree list (경로만 표시) |
핵심 기능
-
Hooks
worktree 생성, 커밋, 머지, 삭제 전후에 명령을 실행합니다. 예를 들어
pre-start에서 의존성을 설치하고,post-start에서 개발 서버를 백그라운드로 띄우고,pre-merge에서 테스트를 돌릴 수 있습니다. 저장소에 두는 프로젝트 훅(.config/wt.toml)은 실행 전에 승인을 받습니다. -
LLM 커밋 메시지
diff로 프롬프트를 만들어 외부 명령에 넘기고, 돌아온 텍스트로 커밋 메시지를 씁니다.
wt merge,wt step commit,wt step squash에 연동되며, 공식 문서에claude -p를 Haiku 모델로 호출하는 설정 예시가 있습니다. -
머지 워크플로
wt merge main한 번으로 커밋, squash, main 위로 rebase, fast-forward 머지, worktree와 브랜치 정리까지 진행합니다. PR로 머지하는 경우에는wt step commit으로 커밋하고 머지 후wt remove로 정리합니다. -
빌드 캐시 공유
target/,node_modules/같은 디렉터리를 새 worktree에 복사할 때 파일 시스템이 지원하면 reflink(디스크 블록을 공유하는 복사)를 씁니다. APFS, btrfs, XFS, ReFS가 해당하며, 공식 문서는 Rust 프로젝트의 첫 빌드가 약 68초에서 약 3초로 줄어든 예를 듭니다. -
목록과 picker
wt list --full은 브랜치별 CI 상태와 AI가 만든 요약을 함께 보여 줍니다. 대화형 picker에서는 CI 상태, diff, 로그, PR과 댓글을 미리 보며 worktree를 고를 수 있습니다. -
그 밖의 기능
wt switch pr:123으로 PR 브랜치로 바로 이동하고,hash_port템플릿 필터로 worktree마다 다른 개발 서버 포트를 줍니다. 사용자 정의wt <name>명령(alias)과 브랜치별 변수도 지원합니다.
Claude Code 플러그인
wt config plugins claude install로 설치하면 다음 기능이 추가됩니다.
- 설정 스킬(
/worktrunk) — LLM 커밋 메시지, 프로젝트 훅, worktree 경로 템플릿 설정과 셸 통합 문제 해결을 Claude가 도와줍니다. Worktrunk 관련 질문이 나오면 Claude Code가 이 스킬을 자동으로 불러오도록 설계되어 있습니다. - 세션 상태 표시 —
wt list에서 Claude가 작업 중인 worktree는 🤖, 입력을 기다리는 worktree는 💬로 표시됩니다. - worktree 격리 연동 — Claude Code 에이전트가 격리된 worktree(
isolation: "worktree")를 만들 때 기본git worktree add대신wt switch --create와wt remove를 거치므로, Worktrunk의 이름 규칙과 훅이 그대로 적용됩니다. /wt-switch-create스킬 — 세션을 떠나지 않고 새 worktree를 만들어 들어가 작업을 시작합니다./wt-diff패널 — 대화 옆에 패널을 열어, 세션이 작업한 worktree 목록과 선택한 worktree의 변경 내용을 보여 줍니다.
플러그인과 별개로, wt list statusline --format=claude-code를 ~/.claude/settings.json의 statusLine 명령으로 지정하면 Claude Code 상태줄에 worktree 상태, 모델, 컨텍스트 사용량을 표시할 수 있습니다.
사용 방법
# 설치 (macOS, Linux)
brew install worktrunk && wt config shell install
# 새 기능용 worktree 만들기
wt switch --create feature-auth
# 모든 worktree 상태 보기
wt list
# 작업이 끝나면 main으로 머지하고 정리
wt merge main
에이전트 여러 개를 병렬로 돌릴 때는 worktree마다 Claude Code를 실행하고 작업을 넘깁니다. -x는 전환 후 실행할 명령이고, -- 뒤의 인자는 그 명령에 전달됩니다.
wt switch -x claude -c feature-a -- 'Add user authentication'
wt switch -x claude -c feature-b -- 'Fix the pagination bug'
wt switch -x claude -c feature-c -- 'Write tests for the API'
알아두면 좋은 점
- 셸 통합이 필요합니다 —
wt switch가 현재 셸의 디렉터리를 바꾸려면 설치 후wt config shell install을 실행해야 합니다. - Windows 이름 충돌 —
wt는 Windows Terminal 명령과 이름이 겹칩니다. Winget은git-wt로도 설치하므로git-wt config shell install처럼 쓰거나, Windows Terminal의 앱 실행 별칭을 끄면 됩니다. - reflink가 없는 파일 시스템 — ext4와 NTFS에서는 빌드 캐시가 파일 단위로 전부 복사됩니다.
/wt-diff패널의 버전 조건 — 플러그인 hooks 모듈을 불러오는 Claude Code 버전에서만 동작합니다. 이전 버전에서는 패널을 뺀 나머지 기능만 동작합니다.- LLM 커밋 설정의 버전 조건 — 공식 예시의
claude -p ... --safe-mode설정은 Claude Code 2.1.169 이상이 필요합니다. - 문서 — 전체 명령과 설정은 worktrunk.dev에, Claude Code 연동은 Agent Integration 문서에 정리되어 있습니다.