claudekit / tools / worktrunk
[ Tool · Development ]

Worktrunk

AI 에이전트를 병렬로 돌리기 위한 git worktree 관리 CLI. 브랜치 이름만으로 worktree를 만들고, 전환하고, 정리하며, `wt switch -c -x claude feat` 한 줄로 새 worktree에서 Claude Code를 바로 실행합니다. Claude Code 플러그인을 설치하면 `wt list`에 세션 상태가 표시되고, 에이전트가 만드는 worktree도 Worktrunk 규칙을 따릅니다.

max-sixty/worktrunk ·updated
$ brew install worktrunk && wt config shell install copy

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를 브랜치 이름으로 지정하고 경로는 템플릿으로 계산해, 이 과정을 명령 하나로 줄입니다.

핵심 명령

작업Worktrunkgit만 쓸 때
worktree 전환wt switch featcd ../repo.feat
만들고 Claude 실행wt switch -c -x claude featgit worktree add -b feat ../repo.feat && cd ../repo.feat && claude
정리wt removecd ../repo && git worktree remove ../repo.feat && git branch -d feat
상태와 함께 목록 보기wt listgit 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 문서에 정리되어 있습니다.
§ 7

See also

same category · curated
[01]
[MCP] ARTEMIS · 자연어 지시를 Android 자동화로 바꾸는 오픈소스 에이전트. MCP 서버로 Claude Code에 연결하면 실기기나 에뮬레이터에서 앱을 조작해 테스트를 진행하고, 스크린샷과 Logcat 로그를 받아 옵니다. 기기 조작은 ARTEMIS가 자체 LLM으로 백그라운드에서 수행합니다.
tool · claudekit.io / tools / artemis
[02]
[Tool] Claude Quickstarts · Claude API로 배포 가능한 애플리케이션을 빠르게 만들기 위한 프로젝트 모음. 고객 지원 에이전트, 금융 데이터 분석, computer use, 브라우저 자동화, Claude Managed Agents 기반 Slack, Linear, Sentry 연동 앱까지 바로 실행할 수 있는 예제를 제공합니다. 일부 퀵스타트는 Claude Code가 설정 과정을 안내합니다.
tool · claudekit.io / tools / claude-quickstarts
[03]
[Plugin] Superpowers · 브레인스토밍, TDD, 체계적 디버깅, 계획 수립/실행, 코드 리뷰 등 전문 개발 워크플로우를 스킬 기반으로 자동화.
tool · claudekit.io / tools / superpowers
§ 8

자주 묻는 질문

자주 묻는 질문
§ 8.1
Worktrunk는 무엇인가요?
AI 에이전트를 병렬로 실행하기 위해 만든 git worktree 관리 CLI입니다. worktree를 브랜치 이름으로 다루고 경로는 설정한 템플릿으로 계산하므로, 브랜치를 다루듯 worktree를 만들고 전환하고 정리할 수 있습니다.
§ 8.2
Claude Code와 어떻게 함께 쓰나요?
`wt switch -c -x claude feat`처럼 worktree를 만들면서 바로 Claude Code를 실행할 수 있습니다. `wt config plugins claude install`로 플러그인을 설치하면 `wt list`에 세션 상태(🤖 작업 중, 💬 대기)가 표시되고, 에이전트가 만드는 worktree도 `wt switch --create`를 거칩니다.
§ 8.3
어떻게 설치하나요?
macOS와 Linux에서는 `brew install worktrunk && wt config shell install`, Rust 환경에서는 `cargo install worktrunk`로 설치합니다. `wt config shell install`은 `wt` 명령이 디렉터리를 이동할 수 있도록 셸 통합을 설정합니다.
§ 8.4
Windows에서도 쓸 수 있나요?
Winget으로 설치할 수 있습니다. `wt`가 Windows Terminal 명령과 겹치기 때문에 Winget은 `git-wt`라는 이름으로도 설치하며, Windows Terminal의 앱 실행 별칭을 끄면 `wt`를 그대로 쓸 수 있습니다.
§ 8.5
Claude Code 말고 다른 에이전트도 지원하나요?
Codex, OpenCode, Pi, oh-my-pi, Gemini CLI용 플러그인도 제공합니다. `wt list`의 세션 상태 표시는 모두 지원하지만, 설정 스킬, worktree 격리, `/wt-diff` 패널 같은 기능은 에이전트마다 지원 범위가 다릅니다.
§ 8.6
무료로 사용할 수 있나요?
MIT와 Apache-2.0 이중 라이선스로 공개된 오픈소스이며 무료입니다. LLM 커밋 메시지 기능은 Claude Code 같은 외부 명령을 호출하므로, 그 도구의 사용량은 따로 듭니다.