2026년 11월 6일 GitHub Trending(전체·Rust 근처)에 max-sixty/worktrunk가 올랐습니다. 이 글 작성 시점 API 기준 스타 11,663, 최신 릴리스 v0.81.0(2026-10-20), 라이선스 MIT OR Apache-2.0(이중), 홈페이지 worktrunk.dev. Claude Code·Codex·OpenCode처럼 장시간 돌아가는 에이전트를 5~10개 병렬로 붙일 때, 네이티브 git worktree의 UX 마찰을 줄이는 Rust CLI입니다.
이 글은 초보 튜토리얼이 아닙니다. 브랜치 주소 지정·경로 템플릿·훅 생명주기·reflink CoW 캐시·머지 파이프라인·저장소/크레이트 구조·Windows git-wt 충돌, 그리고 이 박스(ext4)에서 실제로 돌린 wt switch --create/list/remove 실측을 실무자 기준으로 정리합니다. 오늘 오전 Opensource 딥다이브(vercel-labs/agent-browser)와는 계층이 다릅니다 — 브라우저는 AXTree, 이쪽은 저장소 작업 공간입니다.
한 줄 정의와 핵심 숫자
worktrunk(기본 바이너리 이름 wt)는 worktree를 브랜치 이름으로 다루게 만드는 CLI입니다. 경로는 설정 가능한 템플릿(worktree-path, MiniJinja)으로 계산되고, 같은 인자에 경로를 넣어도 됩니다. 문서가 강조하는 문제는 단순합니다. 에이전트마다 작업 디렉터리가 필요하지만, git worktree add -b feat ../repo.feat && cd ../repo.feat처럼 브랜치 이름을 세 번 치는 UX는 병렬 스케일에 맞지 않는다는 것.
| 항목 | 값 (이 글 검증) |
|---|---|
| 저장소 | max-sixty/worktrunk |
| 버전 | 0.81.0 (GitHub release / crates.io / wt --version 일치) |
| 라이선스 | MIT OR Apache-2.0 (LICENSE 파일·crates.io·Homebrew 동일) |
| 스타 / forks | 11,663 / 447 (GitHub API 2026-11-06) |
| crates.io 다운로드 | 41,549 (누적, crates.io API) |
| 언어·에디션 | Rust, edition 2024, rust-version 1.98 |
| 기본 바이너리 | wt (Windows Winget 추가 이름 git-wt) |
| 문서 | https://worktrunk.dev |
왜 worktree인가: 병렬 에이전트의 충돌면
한 워킹 트리에서 에이전트 여러 개가 동시에 파일을 고치면, 스테이징·머지 컨플릭트·미완성 리팩터가 서로 밟습니다. Git worktree는 브랜치마다 별도 디렉터리를 주므로 에이전트 Isolatation의 기본 단위가 됩니다. Worktrunk는 그 위에 생성·전환·목록·제거·머지를 브랜치 UX로 압축하고, 훅으로 의존성/캐시/서버 기동을 붙입니다.
| 작업 | Worktrunk | Plain git |
|---|---|---|
| 전환 | wt switch feat |
cd ../repo.feat |
| 생성 + Claude | wt switch -c -x claude feat |
git worktree add -b feat ../repo.feat && cd … && claude |
| 정리 | wt remove |
git worktree remove + git branch -d |
| 상태 목록 | wt list (ahead/CI/메시지) |
git worktree list (경로 위주) |
| 로컬 머지+정리 | wt merge main |
squash/rebase/ff/remove를 수동 연쇄 |
| PR 브랜치 점프 | wt switch pr:123 |
forge CLI로 브랜치 확인 후 worktree add |
코어 UX: switch · list · remove · merge
wt switch --create feature-auth는 기본 브랜치에서 새 브랜치+worktree를 만들고 전환을 시도합니다. 셸 통합이 없으면 생성은 성공하지만 Cannot change directory 경고가 납니다(박스 실측에서 재현). wt list는 Status·HEAD±·main↕·Remote⇅·Path·Commit·Age·Message를 progressive하게 채웁니다. @는 현재, ↑1은 기본 브랜치 대비 1커밋 ahead입니다.
wt merge는 커밋(옵션으로 LLM 메시지) → rebase/squash → 타깃 fast-forward → worktree/브랜치 정리까지 한 파이프라인으로 묶습니다. v0.81.0의 wt merge --branch는 현재 worktree를 떠나지 않고 다른 worktree 브랜치를 머지할 수 있습니다. wt remove는 머지된 브랜치를 지우고, 같은 커밋이면 백그라운드 삭제로 넘깁니다(실측에서 feature-b 제거 시 확인).
| 커맨드 | 역할 | 실무 메모 |
|---|---|---|
wt switch |
전환/생성/실행(-x)/PR |
--path로 템플릿 밖 배치(실험적, 0.81.0) |
wt list / --full |
상태·CI·LLM 요약 | forge CLI 미로그인 시 CI 칸 공란 |
wt remove |
worktree+조건 브랜치 삭제 | -y로 승인 스킵; untracked면 stash 안내 |
wt merge |
로컬 통합 파이프라인 | 훅 pre/post-merge와 결합 |
wt step … |
commit/squash/rebase/copy-ignored 등 원자 연산 | 훅·alias에서 재사용 |
wt hook |
훅 수동 실행 | foreground 훅은 stdin 상속(0.81.0) |
wt config |
셸·경로·alias·state | wt config shell install 필수에 가깝다 |
아키텍처: 경로 템플릿 · 훅 · CoW · LLM
경로 템플릿 (MiniJinja 3)
기본은 형제 디렉터리 패턴(../repo.branch류)이고, 사용자 설정 예시는 ~/.config/worktrunk/config.toml의 worktree-path = ".worktrees/{{ branch | sanitize }}"입니다. v0.81.0은 MiniJinja 3로 올라갔고, 객체/리스트 렌더는 Python 스타일이라 JSON이 필요하면 | tojson을 씁니다. hash_port 필터로 worktree마다 고유 개발 서버 포트를 줄 수 있습니다.
훅 생명주기
이벤트는 switch / create(start) / commit / merge / remove 축에 pre-*(차단)와 post-*(백그라운드)가 붙습니다. 문서상 create 쪽 이름은 pre-start/post-start입니다. pre-* 실패는 연산을 중단하고, post-*는 로그를 남기며 비동기로 돕니다. 콜드 스타트 제거 레시피는 post-start = "wt step copy-ignored"입니다. 0.81.0부터 foreground 훅은 stdin을 상속해 gum confirm 같은 대화형 확인이 가능합니다(동시/백그라운드 훅은 EOF).
| 이벤트 | pre (blocking) | post (background) |
|---|---|---|
| switch | pre-switch | post-switch |
| create/start | pre-start | post-start |
| commit | pre-commit | post-commit |
| merge | pre-merge | post-merge |
| remove | pre-remove | post-remove |
CoW 빌드 캐시: wt step copy-ignored
Gitignored 파일(target/, node_modules/, .env 등)을 worktree 사이에 복사합니다. 파일시스템은 지원 시 reflink합니다: APFS(macOS), btrfs·XFS(Linux), ReFS(Windows). ext4·NTFS는 full copy로 떨어지고 요약에 (full copy)가 뜹니다. 문서의 14GB target/ 예시(업스트림 벤치 수치, 이 박스에서 재현하지 않음):
| 방식 | 시간 (문서) | 추가 디스크 (문서) |
|---|---|---|
cp -R full copy |
2m | 14GB |
cp -Rc / wt step copy-ignored (reflink) |
20s | ~0 |
Rust 쪽 문서 노트는 reflink 복사 후 첫 빌드가 ~68s→~3s로 줄어든다고 적습니다(의존성 재사용). 제한은 .worktreeinclude(gitignore 스타일 교집합)와 [step.copy-ignored] exclude입니다. 이 박스 루트 FS는 ext4라서 CoW 이득은 기대하지 않는 것이 맞습니다.
LLM 커밋 · 목록 요약 · 에이전트 플러그인
[commit.generation]에 Claude 등 외부 명령을 걸어 diff 기반 커밋 메시지를 만들 수 있습니다. wt list --full은 CI 상태와 AI 요약을 붙입니다. Claude Code / OpenCode 플러그인은 에이전트가 만든 worktree를 wt switch --create/wt remove 경로로 우회시킵니다(0.81.0 OpenCode 2 지원 강화).
저장소·크레이트 구조
| 경로 | 역할 |
|---|---|
src/main.rs, src/cli/ |
CLI 엔트리·도움말 |
src/commands/ |
switch/list/remove/merge/step/hooks/picker… |
src/copy.rs |
reflink_or_copy + rayon 병렬 디렉터리 복사 |
src/config/, src/shell/ |
설정·셸 래퍼 |
src/llm.rs |
커밋/요약 LLM 호출 경로 |
src/git_wt.rs |
Windows git-wt 바이너리 이름 대응 |
plugins/, skills/ |
Claude/에이전트 스킬·플러그인 |
docs/ |
worktrunk.dev Astro 문서 소스 |
hooks/, templates/ |
예제 훅·템플릿 |
| 바이너리 타깃 | wt(default-run), git-wt, 라이브러리 worktrunk |
설치·실행 (검증된 경로)
# 문서 권장
brew install worktrunk && wt config shell install
cargo install worktrunk && wt config shell install
# 이 박스 실측: GitHub release musl 바이너리
# worktrunk-x86_64-unknown-linux-musl.tar.xz (v0.81.0)
./wt --version # → wt v0.81.0
Windows는 wt가 Windows Terminal과 충돌하므로 Winget이 git-wt를 추가로 설치합니다. Terminal 앱 실행 별칭을 끄면 wt를 직접 쓸 수 있습니다. Arch는 pacman -S worktrunk, conda-forge/Pixi 피드스톡도 있습니다.
| 배포 채널 | 명령 | 비고 |
|---|---|---|
| Homebrew | brew install worktrunk |
macOS·Linux bottle, 0.81.0 |
| Cargo | cargo install worktrunk |
소스 빌드, rustc ≥1.98 |
| GitHub Release | 플랫폼별 .tar.xz/.zip |
이 글 스모크에 사용 (musl x86_64, ~27.7 MB) |
| Winget | winget install max-sixty.worktrunk |
git-wt 별칭 |
| Arch | pacman -S worktrunk |
공식 레포 |
박스 실측 (2026-11-06 KST)
환경: 박스 Linux x86_64, 루트 FS ext4, 바이너리 worktrunk-x86_64-unknown-linux-musl/wt 29,099,264 bytes (~27.7 MB), 버전 wt v0.81.0. 셸 통합은 설치하지 않은 채 호출했습니다.
| 단계 | 결과 | 벽시계 |
|---|---|---|
wt --version |
wt v0.81.0 |
— |
throwaway git init + 초기 커밋 |
main @ 6fe48d9 | — |
wt switch --create feature-auth |
형제 경로 demo-repo.feature-auth 생성; cd 경고 |
34 ms |
wt switch --create feature-b |
세 번째 worktree | 21 ms |
| feature-auth에 커밋 | ↑1, message “Add auth note” |
— |
wt list |
Status/ahead/Path/Commit 컬럼 정상 | — |
wt remove feature-b -y |
백그라운드 제거(main과 동일 커밋) | 32 ms |
| 최종 worktree | main + feature-auth만 잔존 | — |
해석: 생성/제거 자체는 수십 밀리초 수준으로 가볍습니다. 병목은 보통 post-start의 copy-ignored·패키지 설치·에이전트 기동 쪽입니다. 셸 통합 없이는 자동화 스크립트가 경로를 직접 추적해야 합니다.
비교: plain git · 역할 인접 도구
| 축 | plain git worktree |
worktrunk 0.81.0 |
|---|---|---|
| 주소 지정 | 경로 중심 | 브랜치(+경로) 중심 |
| 상태 표 | 경로·HEAD | ahead/CI/메시지/Age |
| 자동화 | 직접 스크립트 | 훅·alias·step 조합 |
| 캐시 공유 | 수동 cp/rsync | reflink copy-ignored |
| 머지 UX | 다단계 | wt merge 파이프라인 |
| 에이전트 결합 | 없음 | -x, Claude/OpenCode 플러그인 |
| 대가 | 표준만 알면 됨 | 셸 래퍼·설정·Windows 이름 충돌 |
유사 ‘매니저’ 이름을 지어 비교표를 부풀리지는 않습니다. 검증 가능한 대비는 네이티브 git worktree와, 오늘 오전 다룬 agent-browser(브라우저 자동화) / 11-03 agent-desktop(네이티브 GUI)처럼 다른 계층의 에이전트 도구입니다. Worktrunk는 그 도구들이 돌아갈 저장소 슬롯을 병렬로 늘리는 쪽에 있습니다.
트레이드오프·주의점
| 이슈 | 내용 | 대응 |
|---|---|---|
| 셸 통합 필수에 가까움 | 서브프로세스는 부모 cwd를 못 바꿈 | wt config shell install 후 셸 재시작 |
Windows wt 충돌 |
Windows Terminal 예약 | git-wt 사용 또는 실행 별칭 해제 |
| CoW FS 의존 | ext4/NTFS는 full copy | btrfs/XFS/APFS/ReFS에서 이득; 아니면 디스크·시간 예산 |
| LLM 기능 | 외부 CLI·API 필요 | [commit.generation] 미설정 시 해당 경로 비활성 |
| 훅 동시성 (0.81.0) | prune/remove pre-hook 동시 실행 | 공유 상태 쓰는 훅은 조율 필요 |
| 템플릿 브레이킹 | MiniJinja 3·undefined filter 엄격화 | default/tojson 가드 |
| 바이너리 크기 | musl 릴리스 ~27.7 MB | CI 캐시·설치 채널 선택 |
실무 레시피 (짧게)
# 병렬 에이전트 세 칸
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'
# 프로젝트 훅 예 (문서)
# .config/wt.toml
# [post-start]
# copy = "wt step copy-ignored"
# PR로 바로 점프
wt switch pr:123
정리하면, Worktrunk 0.81.0은 ‘git worktree를 조금만 감싼 스크립트’가 아니라 병렬 에이전트 운영을 위한 worktree 런타임에 가깝습니다. 경로 템플릿·훅·CoW·머지·forge 연동을 한 CLI에 모았고, 박스에서 확인한 생성/제거 지연은 무시할 수준이었습니다. 남는 숙제는 셸 통합 정착과, 파일시스템이 reflink를 주는지 먼저 재는 일입니다.