AI 코딩 에이전트를 위한 Git worktree 워크플로우 도구

AI 코딩 에이전트들은 격리된 환경에서 가장 잘 작동합니다:

병렬 실행(Parallel execution): 여러 에이전트를 간섭 없이 동시에 실행할 수 있습니다.
깨끗한 분리(Clean separation): 각 기능은 자체 작업 디렉터리를 갖게 됩니다.
실행 엔진(Run engine): '사용하고 폐기(Use and discard)' 워크플로우를 따릅니다. 즉, worktree를 생성하고, 에이전트를 실행하며, 병합한 후, 정리합니다. 사람을 위한 대화형(wt run -i) 방식과 CI/오케스트레이터용 비대화형(wt run) 방식이 있습니다.

npm install -g agent-worktree

최신 버전으로 업데이트하려면:

wt update

Windows 사용자를 위한 참고 사항—wt update는 npm 패키지를 재설치하며, 만약 어떤 wt 프로세스가 실행 중이라면 실패합니다. 왜냐하면 Windows가 실행 중인 .exe 파일을 잠그기 때문입니다. 따라서 업데이트하기 전에 wt를 실행하는 모든 셸을 종료하십시오.

셸 통합은 자동으로 설치됩니다. 수동으로 재설치하려면:

wt setup

지원되는 셸: bash, zsh, fish, PowerShell

# worktree를 생성하고 진입합니다
wt new feature-x
# ... 개발 및 커밋 ...
...

기타 유용한 명령어:

wt ls # 모든 worktree 목록을 표시합니다 (BASE 브랜치 정보 포함)
wt cd feature-y # 다른 worktree로 전환합니다
wt cd # 메인 리포지터리로 돌아갑니다

하나의 엔진: worktree 생성 → 내부에서 에이전트 실행 (WT_* 환경 변수 주입) → 결과에 따라 디스패치(dispatch). 에이전트 명령어는 -- 뒤에 오며, 셸 없이 직접 실행되므로 따옴표 오류가 없습니다. 실패하더라도 검사를 위해 worktree를 항상 보존합니다.

에이전트가 종료된 후 사용자가 결정합니다:

wt run -i -- claude
wt run fix-bug -i -- codex --some-flag

에이전트가 종료되면 (충돌 또는 Ctrl+C로 인해 종료되더라도—신호는 에이전트에게만 도달합니다), wt는 worktree를 확인합니다:

변경 사항 없음(No changes) → 정리하고, 프롬프트 없이 종료
커밋만 있음(Only commits) → BASE 브랜치로 병합([m]) / worktree 유지([q])
미커밋된 변경 사항(Uncommitted changes) → 에이전트 재개방([r]) / worktree 유지([q])

worktree가 유지되면, 사용자의 셸은 그 안으로 전환됩니다 (git commit, 그리고 wt merge). 대화형 세션은 결정하는 즉시 종료 코드 0을 반환하며, 기존 worktree 내부에서 새 세션을 시작하는 것은 거부됩니다.

사전에 정책 선언 — CI/오케스트레이터/ralph-style 루프의 경우, 쉘 통합이 필요하지 않습니다:

wt run fix-bug -- claude -p "fix the bug" --dangerously-skip-permissions
wt run --on-success merge --json -- codex exec "add tests"

--json은 단일 결과 객체를 stdout에 출력합니다 (에이전트 stdout은 stderr로 리디렉션됩니다). 기타 플래그: --base <branch>, -s <strategy> (squash/merge), -H (pre-merge hooks 건너뛰기). --on-success/--json은 헤드리스 환경 전용이며 -i와 충돌합니다.

기본값은 ~/.agent-worktree입니다.
. AGENT_WORKTREE_DIR을 통해 덮어쓸 수 있습니다.

:

export AGENT_WORKTREE_DIR=/data/agent-worktree

[general]
merge_strategy =

거부됩니다. 심볼릭 링크 항목은 완전히 건너뜁니다. 복사본은 파일 시스템이 지원하는 경우 Copy-on-Write를 사용하므로, `copy_files = ["node_modules"]`와 같은 작업도 거의 무료입니다.

훅 신뢰 경계(Hook trust boundary) — 훅은 `sh -c` (또는 Windows의 `cmd /C`)를 통해 실행되며, 샌드박싱이나 시간 제한이 없습니다. `.agent-worktree.toml`을 커밋된 셸 스크립트와 같게 취급하세요. 직접 실행할 훅만 있는 저장소(repos)를 대상으로 합니다.

훅 현재 작업 디렉터리(Hook CWD) — 모든 훅은 워크트리 루트를 작업 디렉터리로 하여 실행됩니다.

서브모듈(Submodules) — `git worktree add`는 서브모듈 디렉터리를 비워두기 때문에, `.gitmodules`가 존재하면 새 워크트리가 자동으로 `git submodule update --init --recursive`를 실행합니다. Git은 워크트리별로 서브모듈의 gitdirs를 유지하므로, 모든 워크트리가 네트워크를 통해 모든 서브모듈을 다시 클론하게 됩니다. 깊은 트리의 경우 몇 분이 걸릴 수 있습니다. `submodule_jobs` (기본값 8)는 클론 병렬성을 설정하며, 이를 건너뛰고 수동으로 초기화하려면 `submodules = false`를 설정하세요.

— 상대 경로는 워크트리 내부에서 해결되지 않으며, 감지되면 생성 시 경고가 출력됩니다. `core.hooksPath`

훅 환경(Hook environment) — 모든 훅은 다음 변수들을 받으므로, 스크립트는 경로를 하드코딩하지 않고 참조할 수 있습니다:

| 변수 | 값 |
| :--- | :--- |
| `WT_MAIN_REPO` | 메인 저장소 루트 |
| `WT_WORKTREE` | 새 워크트리의 절대 경로 |
| `WT_BRANCH` | 워크트리의 브랜치 이름 |
| `WT_BASE_BRANCH` | 기본 브랜치 (`new`의 생성 소스, `merge`의 병합 대상) |

Copy-on-Write가 없는 파일 시스템에서는 심볼릭 링크가 무거운 디렉터리에 대해 `copy_files`보다 우수합니다: [hooks] post_create = ['ln -s "$WT_MAIN_REPO/node_modules" node_modules']

프로젝트 설정이 전역 설정을 덮어씁니다. `trunk`는 프로젝트 전용이며, 다른 필드는 병합됩니다.

[general]
trunk = "main" # 트렁크 브랜치 (생략 시 자동 감지)
merge_strategy = "merge" # 전역 병합 전략 재정의
...

~/.agent-worktree/
├── config.toml # 전역 설정
└── workspaces/
...

MIT