ZCode용 Git Worktrees

모든 스레드는 자체 워크트리를 얻습니다 — 자동으로. Git Worktrees는 각각의 새로운 ZCode 스레드에 저장소의 격리된 체크아웃을 제공하므로, 스태시, 브랜치 저글링, 또는 서로 덮어쓰기 없이 작업이 병렬로 실행됩니다. 채팅을 시작하세요; 이미 격리되어 있습니다.

/worktree:new fix-auth "Refactor the login flow"   ← worktree + background agent
/worktree                                          ← dashboard: branches, sizes, agents
/worktree:end fix-auth                             ← commit everything, remove cleanly

왜 필요한가

• 제로 설정. 자동 세션 모드(기본적으로 켜짐)는 새 스레드가 시작되는 즉시 자체 워크트리를 제공하며, 스레드를 재개하면 동일한 워크트리로 돌아갑니다. 명령이 전혀 필요 없습니다.

• 작업 손실 없음. 더티 워크트리, 실행 중인 에이전트, 또는 병합되지 않은 브랜치의 제거는 force 없이는 거부됩니다 — 그 경우에도 커밋되지 않은 변경 사항은 먼저 복원 가능한 디렉토리에 스냅샷됩니다(추적된 diff + 추적되지 않은 파일). 브랜치는 기본적으로 유지됩니다.

• 환경이 함께 이동합니다. .env 및 기타(gitignore되고 .worktreeinclude에 나열된 모든 것)는 새 워크트리로 가져오며, setupCommands(pnpm install, docker compose up -d)가 자동으로 실행됩니다.

• 방해하지 않습니다. 워크트리는 중앙 저장소(~/.zcode/worktrees)에 있으며, 저장소는 원래 상태를 유지하고, 보존 정리로 디스크 사용량이 제한됩니다. 어떤 것도 조용히 삭제되지 않습니다.

설치

1. ZCode Desktop에서 설정 → 플러그인 관리를 열고 마켓플레이스 추가를 클릭합니다.

2. 저장소를 붙여넣습니다 — GitHub owner/repo 슬러그 또는 전체 Git URL 모두 작동합니다:

   agallardol/zcode-git-worktrees

3. 카탈로그에서 Git Worktrees를 설치합니다.

4. 아무 git 저장소를 열고 스레드를 시작하세요 — 이미 격리되어 있습니다. 대시보드를 보려면 /worktree를 입력하세요.

요구 사항: ZCode ≥ 3.8.1, PATH에 node ≥ 18, git.

/worktree가 나타나지 않으면: 터미널에서 node --version을 실행하고(MCP 서버는 node가 필요합니다), 설치된 항목에서 플러그인이 활성화되어 있는지 확인하고, 앱이 열려 있는 동안 설치했다면 ZCode를 다시 시작하세요.

Related MCP server: hop-mcp

명령어

그 뒤에는 9개의 MCP 도구(worktrees_create, worktrees_list, worktrees_status, worktrees_remove, worktrees_cleanup, worktrees_prune, worktrees_snapshot, worktrees_set_task, worktrees_auto_session), 모델용 스킬, 그리고 훅이 있습니다 — 그래서 에이전트는 병렬 또는 격리된 작업을 요청할 때 스스로 워크트리를 사용할 수 있습니다.

자동 세션 워크트리 (기본적으로 켜짐)

저장소의 메인 체크아웃에서의 모든 새 세션은 자체 워크트리(zcode/sess-…)를 얻습니다. 재개하면 동일한 워크트리로 돌아가며, 메인 체크아웃에 대한 파일 편집은 차단되고 세션 워크트리로 리디렉션됩니다. 설정 → 플러그인 → Git Worktrees 또는 /worktree:auto로 전환할 수 있습니다(가장 최근 변경이 우선). 저장소는 항상 옵트아웃할 수 있습니다:

// .zcode/worktree.json in the repo
{ "autoSession": false }

저장소 측 구성 (선택 사항)

.worktreeinclude — gitignore 스타일 패턴; 또한 gitignore된 파일만 새 워크트리로 가져옵니다(추적된 파일은 절대 중복되지 않습니다):

.env
config/secrets.json

.zcode/worktree.json — 명시적 파일, 수명주기 훅, 자동 세션 재정의:

{
  "autoSession": true,
  "copyFiles": [".env.local"],
  "setupCommands": ["pnpm install"],
  "preRemoveCommands": ["docker compose down"]
}

플러그인 설정(설정 → 플러그인 → Git Worktrees): 워크트리 루트, 기본 베이스(fresh = 오프라인 폴백이 있는 origin/HEAD, 또는 head), 최대 보존 일수(14), 프로젝트당 최대 워크트리 수(15).

안전 모델

• 저장소를 벗어나는 것 없음 — 이름은 경로 및 git-ref 안전성에 대해 검증되고(트래버설, .lock, 대소문자 쌍, 유니코드 트릭 모두 거부), 전체 경로는 심볼릭 링크로부터 보호되며, 저장소 경로는 정규화됩니다. 실패한 git worktree add는 해당 브랜치를 롤백합니다.

• 동시성 안전 — 변경 사항은 프로세스 내 큐와 프로세스 간 잠금 파일로 직렬화됩니다. 병렬 생성은 상태를 잃지 않습니다.

• 자가 복구 — 손상된 상태는 격리되고 재구축되며, 워크트리는 git에서 다시 채택되고, 대역 외 삭제는 prune/cleanup으로 조정됩니다.

• 신뢰할 수 없는 저장소에서 실행 없음 — setupCommands / preRemoveCommands는 명시적으로 생성한 워크트리에서만 실행됩니다. 자동 세션 생성은 저장소 제공 명령을 절대 실행하지 않습니다. 클론된 저장소를 여는 것은 코드 실행이 아닙니다. 모든 git 호출은 execFile을 통해 이루어지며, 유일한 셸 실행은 사용자가 동의한 수명주기 명령뿐입니다.

영감을 준 도구들과 비교하면: PR 번호 체크아웃과 .worktreeinclude 의미론은 Claude Code에서, 삭제 전 스냅샷과 중앙 저장소는 Codex에서, 제한된 보존은 Cursor/Codex에서 왔습니다 — 여기에 백그라운드 에이전트 작업 오케스트레이션과 하드 편집 격리가 추가되었으며, 이는 그들 중 어느 것도 플러그인에 노출하지 않습니다.

테스트

npm test   # 129 tests: 80 unit (validators, state, carry-over, hooks, edit guard)
           #        + 13 integration (real MCP stdio JSON-RPC + protocol edges)
           #        + 36 adversarial & security (hostile names, races, corrupt
           #           state, out-of-band damage, exploit regressions)

CI runs the suite on macOS and Linux (Node 20 and 22).

테스트 스위트는 전적으로 로컬 픽스처에 대해 실행됩니다 — 네트워크 없음, 모델 호출 없음.

참고 사항 및 제한 사항

• 자동 세션 격리는 명령에 대해서는 소프트, 편집에 대해서는 하드입니다: Write/Edit 도구는 PreToolUse 가드에 의해 메인 체크아웃에 대해 차단되고, Bash는 주입된 컨텍스트에 의해 안내되며 정적으로 감시되지 않습니다.

• ZCode에는 세션 종료 이벤트가 없으므로 종료 시 자동으로 커밋되거나 삭제되는 것이 없습니다 — /worktree:end가 명시적인 종료 지점이며, 보존 정리가 유휴 상태로 남은 것을 수집합니다.

• 자동 세션에 대한 설정 변경 시 한 세션 지연이 있습니다(훅은 MCP 서버가 세션 시작 시 동기화하는 마커를 읽습니다).

라이선스

MIT © Alfredo Gallardo