wtx

내장 MCP 서버를 갖춘 Git 워크트리 관리자. 터미널에서 격리된 작업 공간을 생성·확인·정리하고, AI 코딩 에이전트가 직접 처리하도록 할 수도 있습니다.

병렬 AI 코딩 에이전트가 git stash 저글링을 구식으로 만들었습니다. 하지만 git worktree add ../foo -b foo && cd ../foo && cp ../.env . 같은 명령을 하루에 다섯 번씩 반복하고 싶은 사람은 아무도 없습니다. wtx는 워크트리를 사람과 에이전트 모두에게 한 단어로 끝나는 워크플로우로 만들어 줍니다:

$ wtx new fix-login
✔ created worktree fix-login
  path:   ~/code/myapp/.worktrees/fix-login
  branch: wt/fix-login (new)
  copied: .env, .env.local

에이전트는 MCP를 통해 동일한 기능을 얻을 수 있습니다:

{ "name": "create_worktree", "arguments": { "name": "fix-login", "setup": "npm install" } }

왜 wtx인가

• 하나의 도구, 두 가지 인터페이스. 당신을 위한 빠른 CLI와, Claude Code, Cursor, Codex, 그리고 MCP를 지원하는 모든 에이전트를 위한 MCP 서버(wtx mcp)를 제공합니다.

• 의존성 제로. git으로만 명령을 내보내는 단일 Node.js 바이너리입니다. 감사할 것도, 고장날 것도 없습니다.

• 정리 관리. 모든 워크트리의 디스크 사용량과 마지막 활동 시각을 보여줍니다. wtx clean --dry-run으로 오래된 node_modules 클론이 차지하는 수 기가바이트를 되찾으세요.

• 기본적으로 안전. 변경 사항이 있는 워크트리 삭제를 거부하고, 메인 체크아웃은 절대 건드리지 않으며, 브랜치는 완전히 병합된 경우에만 삭제합니다. .git/info/exclude로 .worktrees/를 숨겨 .gitignore를 오염시키지 않습니다.

• 필수 기능이 기본 제공됩니다. 새 워크트리에 env 파일을 복사하고 프로젝트의 setup 훅을 자동으로 실행합니다.

설치

npm install -g wtx        # or: brew install wtx (planned)

Node.js ≥ 18과 최신 git이 필요합니다.

빠른 시작

$ cd myapp
$ wtx new feat-search          # isolated workspace at .worktrees/feat-search on branch wt/feat-search
$ cd $(wtx path feat-search)   # jump in
$ wtx ls                       # see every workspace, its state and size
NAME       BRANCH         STATUS       AGE      SIZE     PATH
myapp*     main           ✓ clean      2d ago   412 MB   ~/code/myapp
feat-api   wt/feat-api    ● dirty (1)  3h ago   38 MB    ~/code/myapp/.worktrees/feat-api
$ wtx clean --dry-run          # preview reclaimable space
· feat-api (branch merged, 38 MB)
would free: 38 MB · kept 0 worktree(s)

명령어

전역 플래그: --json (기계가 읽을 수 있는 출력), --base <ref>, --setup <cmd>, --no-copy, --no-setup.

AI 에이전트에서 사용하기 (MCP)

MCP 클라이언트 설정에 추가하세요:

// e.g. claude_desktop_config.json / opencode.json / .mcp.json
{
  "mcpServers": {
    "wtx": { "command": "npx", "args": ["-y", "wtx", "mcp"] }
  }
}

서버는 list_worktrees, create_worktree, remove_worktree, clean_worktrees 네 가지 도구를 제공합니다. 선택적으로 repo_path를 받으며, 지정하지 않으면 서버의 작업 디렉터리를 사용합니다. 응답은 JSON이므로 에이전트는 메인 체크아웃에서 브랜치를 전환하지 않고도 생성 → 작업 → 제거 절차를 연결할 수 있습니다.

에이전트 프롬프트 예시: "develop을 기반으로 oauth-fix라는 워크스페이스를 만들고, 그 안에서 pnpm install을 실행한 다음 경로를 알려줘."

설정

저장소 루트에 wtx.config.json(또는 .wtxrc)을 넣으세요:

{
  "dir": ".worktrees",
  "copyFiles": [".env", ".env.local"],
  "setup": "pnpm install",
  "branchPrefix": "wt/"
}

안전 모델

• rm 또는 clean으로 메인 워크트리를 제거하는 일은 절대 없습니다.

• 변경 사항이 있는 워크트리는 clean에서 항상 보존됩니다. rm으로 제거하려면 --force가 필요합니다.

• 브랜치는 기본 브랜치(origin/HEAD → main → master 폴백)에 완전히 병합된 경우에만 삭제됩니다.

• 워크트리 디렉터리는 .worktrees/ 아래에 있고 .git/info/exclude를 통해 제외되므로 .gitignore는 그대로 유지됩니다.

• 이름은 살균 처리됩니다. ../evil과 같은 경로 우회는 거부됩니다.

비교

개발

git clone https://github.com/willkhinz/wtx && cd wtx
npm install
npm test        # build + 32 integration/unit tests
node dist/src/cli.js help

구조: src/core.ts (엔진), src/cli.ts (사람용 UI), src/mcp.ts (에이전트용 UI). MCP 구현은 의존성이 없는 개행 분리(NDJSON) JSON-RPC 2.0입니다.

로드맵

• wtx exec <name> -- <cmd> 모든 워크트리 대상 명령 실행

• 워크트리별 tmux/iTerm 세션 시작

• Homebrew formula 추가

• GitHub Action: 워크트리별 프리뷰를 PR에 댓글로 달기

라이선스

MIT