Claude Worktree (cwt): 코딩 에이전트를 위한, Git Worktree 기반의 작업 공간 격리 도구

읽을거리&정보공유
, , , ,
1

Claude Worktree (cwt): 코딩 에이전트를 위한, Git Worktree 기반의 작업 공간 격리 도구
Claude Worktree (cwt): 코딩 에이전트를 위한, Git Worktree 기반의 작업 공간 격리 도구1072×362 14.1 KB

Claude Worktree (cwt) 소개

Claude Worktree (cwt) 는 코딩 에이전트가 작업을 수행할 때, Git 워크트리(Git Worktree) 를 효율적으로 사용/관리하여 각 세션을 격리해주는 터미널 기반 도구(TUI)입니다. 최근 Claude CLI와 같은 에이전트형 AI 도구가 등장하면서, 기존 코드를 직접 수정하게 하는 경우가 많아졌습니다. 이 때, 메인 브랜치(main/master branch)나 작업 중인 디렉터리에서 바로 코딩 에이전트를 실행하면 원치 않는 코드 변경이나 충돌이 발생할 위험이 있습니다. Git Worktree는 이를 방지하기 위한 훌륭한 기능이지만, 매번 명령어로 디렉터리를 생성하고 설정을 복사하는 과정이 번거로웠습니다. cwt는 이 과정을 자동화하여 AI 협업 워크플로우를 매끄럽게 만들어줍니다.

최근 코딩 에이전트 사용을 돕는 수많은 도구가 공개되고 있습니다. 어떤 도구는 Docker 컨테이너로 에이전트를 감싸기도 하고, 셸 명령어를 프록시하거나, 아예 IDE를 새롭게 정의하기도 합니다. 하지만 cwt는 매우 단순하고 강력한 전제에서 출발합니다. 바로 "Git 워크트리(worktree)는 AI 코딩 세션을 격리하기 위한 최선의 방법이지만, 수동으로 관리하기는 귀찮다"는 것입니다.

Claude Worktree (cwt) 사용 예시

따라서, Claude Worktree는 개발자의 기존 작업 방식을 바꾸려 하지 않습니다. 단지 복잡한 설정(setup) 과정을 빠르게 단축하는 것을 목표로 합니다. cwt를 실행하면 터미널 사용자 인터페이스(TUI)를 통해 워크트리를 생성, 전환, 삭제할 수 있으며, 세션에 진입할 때 자동으로 claude (혹은 설정된 셸) 인스턴스를 해당 디렉터리에서 실행해 줍니다. 이를 통해 개발자는 메인 작업 공간을 더럽히지 않고, 격리된 환경에서 안전하게 AI와 함께 코드를 작성하고 실험할 수 있습니다.

Claude Worktree vs. 직접 Git Worktree 관리

기존에 Git Worktree를 사용하여 AI 세션을 격리하려면 다음과 같은 번거로운 과정을 거쳐야 했습니다:

  1. git worktree add ... 명령어로 새로운 디렉터리 생성
  2. 필요한 설정 파일(.env)이나 의존성 폴더(node_modules)를 수동으로 복사하거나 심볼릭 링크 생성
  3. 해당 디렉터리로 이동하여 에이전트 실행
  4. 작업이 끝나면 디렉터리를 나오고 git worktree remove 및 폴더 정리

이에 비해, Claude Worktree (cwt) 는 이 모든 과정을 단축키 하나와 자동화 스크립트로 해결합니다. 특히 .env 파일이나 node_modules를 자동으로 심볼릭 링크(symlink) 처리해 주어, 새 워크트리를 만들자마자 즉시 실행 가능한 환경을 제공한다는 점이 가장 큰 차이점입니다.

Claude Worktree의 주요 특징 및 기능

cwt는 Ruby로 작성되었으며 ratatui-ruby를 사용해 직관적인 TUI를 제공합니다. 백그라운드 데몬 없이, 오직 Git 표준 기능만을 사용하여 가볍고 빠르게 동작합니다.

동작 원리 (How it works)

  • 순정 Git 사용: 내부적으로 표준 Git 워크트리 기능을 사용합니다.

  • 네이티브 환경: 세션에 진입하면 cwt는 잠시 중단(suspend)되고, 해당 워크트리 디렉터리에서 claude (또는 선호하는 셸) 프로세스를 직접 실행합니다.

  • 제로 오버헤드: 프로세스를 감싸거나(wrap) 명령어를 가로채지 않습니다. 사용자의 스크립트, 별칭(alias), 워크플로우가 그대로 유지됩니다.

핵심 기능 (Features)

  • 빠른 관리: 워크트리를 즉시 생성, 전환, 삭제할 수 있습니다.

  • 안전 장치 (Safety Net): 세션을 삭제하기 전에 병합되지 않은 변경 사항(unmerged changes)이 있는지 확인하여 실수로 작업을 잃는 것을 방지합니다.

  • 자동 설정 (Auto-Setup): 기본적으로 프로젝트 루트의 .env와 node_modules를 새 워크트리에 심볼릭 링크로 연결합니다.

고급 설정 (Custom Setup Hook)

기본 심볼릭 링크 동작 대신 npm ci를 실행하거나 다른 설정 파일을 복사하고 싶다면, .cwt/setup 스크립트를 작성하여 동작을 커스터마이징할 수 있습니다:

# .cwt/setup 스크립트 작성 및 실행 명령
mkdir .cwt
touch .cwt/setup
chmod +x .cwt/setup

이후, Claude Worktree는 디렉토리 진입 시 .cwt/setup 파일이 존재하면 기본 심볼릭 링크 작업을 건너뛰고 해당 스크립트를 실행합니다. 다음은 이러한 .cwt/setup 스크립트의 예시입니다:

#!/bin/bash
# 이 세션에서 안전하게 수정할 수 있도록 .env를 복사
cp ../.env .

# 심볼릭 링크 대신 의존성을 새로 설치 (더 깔끔한 환경)
npm ci

# 작업 완료 안내
echo "Ready to rock!"

Claude Worktree 설치 방법 (Installation)

Claude Worktree(cwt)는 Ruby Gem 또는 Homebrew를 통해 설치할 수 있습니다:

# Ruby Gem을 사용한 설치 시:
gem install claude-worktree

# Homebrew를 사용한 설치 시:
brew tap bengarcia/tap
brew install cwt


설치 후에는 Git 저장소의 루트 디렉터리에서 cwt 명령어를 실행하면 됩니다. 다음과 같은 단축키를 사용하여 더 빠르게 작업을 수행할 수 있습니다:

단축키 동작 설명
n New Session 새 워크트리를 생성하고 claude를 실행합니다.
Enter Resume TUI를 중단하고 선택한 워크트리 세션으로 진입합니다.
/ Filter 브랜치나 폴더 이름을 검색/필터링합니다.
d Safe Delete 병합되지 않은 변경 사항을 확인 후 삭제합니다.
D Force Delete (Shift+d) 강제로 삭제합니다.
q Quit 프로그램을 종료합니다.

라이선스

Claude Worktree(cwt) 프로젝트는 MIT 라이선스로 공개 및 배포 되고 있습니다.

:github: Claude Worktree 프로젝트 GitHub 저장소



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck: