🌏 다른 언어로 읽기: English | 한국어 | 简体中文 | 繁體中文 (台灣) | 繁體中文 (香港) | 日本語
- 이미지 인식 터미널 붙여넣기:
Cmd+V/Ctrl+Shift+V에서 텍스트는 일반 붙여넣기, 이미지는 파일 경로 입력으로 자동 분기됩니다. - Remote-SSH 클립보드 브리지: 로컬 클립보드 이미지를 원격 터미널로 별도 업로드 없이 바로 전달합니다.
- 충돌 방지 세션 식별자:
repo-name + path hash네임스페이스와 슬러그 충돌 해소 로직으로 같은 이름 저장소도 안전하게 구분합니다. - 레거시 호환 마이그레이션:
@workdir기준으로 기존 세션 prefix도 계속 인식합니다. - No-git 폴백 가시성: git이 없는 폴더도
current project (no git)로 트리에 표시됩니다.
여러 브랜치를 동시에 작업하면서 git worktree와 tmux를 쓰시나요? 그럼 매번 둘을 따로 관리하는 게 얼마나 귀찮은지 아실 겁니다. 이 확장 프로그램이 그 간극을 메워줍니다:
- 원클릭으로 worktree와 tmux 세션을 한 번에 생성
- 트리 뷰에서 모든 worktree와 tmux 상태를 한눈에 확인
- worktree 폴더를 열면 자동으로 해당 tmux 세션에 연결
- VS Code를 껐다 켜도 작업 컨텍스트를 잃지 않음 — 세션은 계속 살아있어요
Claude Code, Codex, OpenCode, Gemini CLI 같은 AI 코딩 에이전트를 tmux 세션 안에서 돌리세요. 에이전트는 백그라운드에서 계속 작업하고, 여러분은 언제든 재접속할 수 있습니다. 심지어 폰에서 Termux로도요.
사이드바에 git worktree와 연결된 tmux 세션들이 한눈에 보입니다. 세션 상태, 패널 개수, 마지막 활동 시간까지 다 표시됩니다.
새 git 브랜치 + worktree + tmux 세션을 한 번에 만들 수 있어요. 새 기능 작업을 바로 시작하세요.
기본 생성 위치는 ~/.tmux-worktrees/<repo-name-hash>/라서 저장소 루트가 지저분해지지 않고, 여러 저장소 사이 경로 충돌도 피할 수 있습니다.
feat/auth, task/my-task 같은 브랜치명도 그대로 입력할 수 있고, tmux 세션/worktree 슬러그는 /를 안전하게 -로 바꿔 충돌 없이 만듭니다.
슬러그가 primary worktree의 main과 충돌하면 자동으로 suffix를 붙여 세션 이름을 유일하게 유지합니다.
새 태스크 브랜치는 첫 publish 전까지 로컬 브랜치로만 유지해서, VS Code가 아직 없는 리모트 브랜치와 Sync를 시도하지 않고 Publish Branch를 계속 보여줍니다. 대신 branch.<name>.vscode-merge-base에 비교 기준 브랜치를 저장해 SCM diff 기준은 유지합니다.
- 터미널에서 연결 — VS Code 통합 터미널에서 tmux 세션 열기
- 에디터에서 연결 — tmux 세션을 에디터 탭으로 띄우기
- 자동 연결 — worktree 폴더 열면 자동으로 세션 연결
- 크기 안정화 연결 — attach 직전에 PTY 크기를 재시도 측정하고 대상 tmux 윈도우를 강제로 resize한 뒤
window-size latest를 복구해, 풀스크린 TUI의 80x24 초기 렌더링과 지속적인 화면 잘림을 함께 줄입니다 - 프롬프트 안정화 연결 — tmux/zellij 세션을 붙이거나 만들기 전에 VS Code/Electron shell integration 환경 변수를 걷어내, multiplexer 안에서 redraw/드래그 선택/backspace 편집이 간헐적으로 깨지는 문제를 줄입니다
- Zellij 안전 부트스트랩 — 새 Zellij 세션을
TERM=dumb대신 실제 터미널 타입으로 시작하고, attach 시 simplified UI를 요청해 VS Code 통합 터미널에서 프롬프트 redraw 깨짐과 glyph 네모 표시를 줄입니다 - Zellij 하이픈 세션명 안전 처리 —
.hermes같은 숨김 저장소 이름에서 만들어지는-...세션명을 Zellij가 CLI 옵션으로 오해하지 않게 attach해, Remote-SSH 에디터 탭에서 help가 떴다가 바로 닫히는 문제를 막습니다 - Zellij 키 전달 — Zellij backend를 선택하면 키보드 레이아웃과 무관한 Alt 시리즈, Shift+Left/Shift+Right, Ctrl+D/Ctrl+Q/Ctrl+G 전달, 콘솔 멀티라인 입력용 Shift+Enter가 터미널 포커스에서 전달되도록 확장이 keybinding을 제공하고, 필요한 터미널 설정 override도 Zellij 활성 상태에서만 적용합니다
- tmux/zellij IPC 소켓 저장 위치를
tmuxWorktree.socketDir(기본값/var/tmp) 설정으로 지정합니다./tmp/대신 POSIX 표준 persistent-temp 디렉토리를 써서 재부팅 후에도 일정 기간 유지되고, macOS의 깊은$TMPDIR가 103바이트 Unix 소켓 경로 제한을 넘는 문제도 회피합니다. - 첫 활성화 시 사용자에게 저장 위치를 묻습니다. Enter로 기본값
/var/tmp사용, 또는 커스텀 경로(예:~/.cache/sockets) 입력. 디렉토리가 없으면 모달로 생성 확인을 받고mkdir -p합니다. - 디렉토리 확정 후, Sync to Shell 옵션으로 shell rc(
~/.zshrc,~/.bashrc/~/.bash_profile,~/.config/fish/config.fish)에 관리되는export TMUX_TMPDIR=... ; export ZELLIJ_SOCKET_DIR=...블록을 기록할 수 있습니다. 다른 터미널에서 실행되는 tmux/zellij도 같은 디렉토리를 쓰게 됩니다. 기록 전에 타임스탬프 백업이 자동 생성됩니다. - 나중에
TMUX: Change Session File Directory또는TMUX: Sync Session File Directory to Shell rc명령으로 언제든 변경할 수 있습니다.
worktree가 삭제된 후 남아있는 tmux 세션을 찾아서 정리합니다. 환경을 깔끔하게 유지하세요.
- 컨텍스트 메뉴에서 패널 분할과 새 윈도우 생성
- worktree 경로를 클립보드에 복사
- worktree를 새 VS Code 창으로 열기
- 이름으로 세션 필터링
- 터미널에서
Cmd+V(macOS) /Ctrl+Shift+V(Linux) 입력 시 클립보드 내용을 먼저 확인합니다 - 텍스트가 있으면 기존 붙여넣기 동작을 그대로 사용합니다
- 이미지가 있으면 임시
.png파일로 저장한 뒤, 해당 경로를 터미널에 입력합니다 - 로컬 환경뿐 아니라 Remote-SSH에서도 동작합니다 (webview 브리지로 로컬 클립보드 이미지를 원격으로 전달)
- 명령 팔레트에서 강제 이미지 붙여넣기:
TMUX: Paste Image from Clipboard
- 같은 저장소 이름이 여러 경로에 있어도 충돌하지 않도록
repo-name + path hash네임스페이스를 사용합니다 @workdir가 현재 저장소 안을 가리키면 레거시 세션 이름도 호환 인식합니다- worktree 슬러그가 충돌하면 부모 폴더명, 이후 경로 해시로 자동 구분합니다
- git 저장소가 아닌 폴더도 트리에
current project (no git)로 표시합니다
프로젝트/
├── main → tmux: "myapp/main" (Claude Code가 리팩토링 중)
├── feature/oauth → tmux: "myapp/feature-oauth" (직접 코딩)
└── fix/memory-leak → tmux: "myapp/fix-memory-leak" (Codex가 분석 중)
각 브랜치에서 AI 에이전트를 독립적으로 돌리고, VS Code로 결과를 확인하세요. 세션은 백그라운드에서 계속 작업합니다.
SSH로 개발 서버에 접속한 상태에서:
- VS Code Remote-SSH로 서버 접속
- TMUX Worktree로 각 브랜치별 세션 관리
- SSH 연결이 끊겨도 tmux 세션은 살아있음
- 집에서도, 카페에서도, 폰에서도 재접속
Termux + SSH로 폰에서 접속해서:
ssh dev-server
tmux attach -t myapp/feature-oauth통근길에 AI 에이전트가 작성한 코드 리뷰도 가능합니다.
| 명령어 | 설명 |
|---|---|
TMUX: Attach/Create Session |
현재 worktree의 tmux 세션에 연결하거나 새로 만들기 |
TMUX: New Task |
새 브랜치 + worktree + tmux 세션 한 번에 생성 |
TMUX: Remove Task |
worktree와 tmux 세션 삭제 |
TMUX: Cleanup Orphans |
고아 tmux 세션 정리 |
TMUX: Smart Paste (Image Support) |
스마트 터미널 붙여넣기: 텍스트는 일반 paste, 이미지는 임시 파일 경로 입력 |
TMUX: Paste Image from Clipboard |
클립보드 이미지를 강제로 저장하고 현재 터미널에 경로 입력 |
VS Code를 열지 않고도 동일한 multiplexer 세션에 붙을 수 있게 해 주는 Go 바이너리입니다. 익스텐션과 똑같은 세션 명명 규칙과 환경변수 정리 로직을 사용하므로, 둘 중 어느 쪽에서 만든 세션이든 다른 쪽에서 그대로 attach할 수 있습니다.
cd cli && go install ./... # ~/go/bin/tmux-worktree-tui 에 설치| 명령어 | 설명 |
|---|---|
tmux-worktree-tui |
인터랙티브 worktree/세션 선택기(Bubble Tea TUI) 실행 |
tmux-worktree-tui open |
현재 디렉토리에 대해 익스텐션이 사용할 tmux/zellij 세션에 attach 또는 생성 |
| 플래그 | 설명 |
|---|---|
--multiplexer tmux|zellij |
VS Code 설정의 multiplexer 값을 무시하고 강제로 선택 |
--print |
해석된 세션명, namespace, slug, 선택된 multiplexer를 출력하고 attach 없이 종료 |
git rev-parse --git-common-dir으로 primary worktree 경로를 찾음. git 저장소가 아닌 폴더는 폴더 자체를 identity root로 사용.- 익스텐션과 동일한
{basename}-{sha1[:8]}_{slug}세션명을 계산. tmuxWorktree.multiplexer,tmuxWorktree.socketDir설정을 워크스페이스.vscode/settings.json→ 사용자 VS Code / Insiders / Cursor / Antigravity 설정 순으로 읽어옴. 못 찾으면tmux+/var/tmp가 기본값.VSCODE_*,ELECTRON_RUN_AS_NODE,TERM_PROGRAM*같은 환경변수를 process env에서 제거하고, 이미 실행 중인 tmux 서버에서도set-environment -gu로 청소해서 새 pane이 shell-integration 마커에 오염되지 않게 함..hermes같은 숨김 폴더에서 생기는-로 시작하는 zellij 세션명을--뒤로 보내 attach 안전성 확보.- tmux 안에서 실행되면
tmux switch-client로 처리하고, 그 외에는syscall.Exec로tmux new-session -A또는zellij attach --create를 현재 프로세스 자리에 직접 실행.
- v1.2.12: VS Code를 linked worktree에서 열었을 때 세션 namespace가 흔들리던 문제를 수정했습니다. 세션명과 관리형 worktree 경로가 이제 primary worktree 기준으로 고정됩니다.
- v1.2.8:
.hermes처럼 숨김 폴더에서 열린 Remote-SSH workspace에서-로 시작하는 Zellij 세션명을 attach할 때 help가 뜨고 바로 종료되던 문제를 수정했습니다. - v1.1.6: AI CLI 워크플로우를 위한 이미지 인식 터미널 붙여넣기(
Cmd+V/Ctrl+Shift+V)와 강제 이미지 붙여넣기 명령 추가. 또한 시작 시 auto-attach 타이밍을 보정해, 가끔 터미널이 작게 렌더링되었다가 창 크기 조절 후 정상화되던 문제를 완화했고, 강제 resize 이후window-size latest를 복구해 지속적인 화면 잘림을 줄였으며, 일부 환경에서 attach 실행이 실패하던 셸 스크립트 파싱 회귀도 수정했습니다. - v1.1.4 - v1.1.5: tmux attach 시 클립보드/패스스루 옵션을 자동 설정해 원격 환경 클립보드 신뢰성 개선.
- v1.1.3: 레거시 세션 prefix 호환 로직 정리로 마이그레이션 안정성 개선.
- v1.1.2: 슬러그 충돌 처리와 no-git 워크스페이스 라벨(
current project (no git)) 추가.
- tmux — 설치되어 있어야 하고 PATH에 있어야 합니다
- git — 설치되어 있어야 하고 PATH에 있어야 합니다
- VS Code 1.85.0 이상
- 확장 프로그램 설치
- VS Code에서 git 저장소 열기
- 액티비티 바(사이드바)에서 TMUX 아이콘 클릭
- 기존 worktree와 tmux 세션이 자동으로 표시됩니다
새 태스크 만들기: TMUX 패널 헤더의 + 버튼 클릭, 브랜치 이름 입력하면 끝!
저장소 (루트)
├── main → tmux 세션: "project-a1b2c3d4_main"
├── feature/login → tmux 세션: "project-a1b2c3d4_feature-login"
└── fix/bug-123 → tmux 세션: "project-a1b2c3d4_fix-bug-123"
각 worktree마다 전용 tmux 세션이 생깁니다. 세션 이름은 repo-name + path hash 네임스페이스와 슬러그를 함께 써서, 같은 저장소 이름이 다른 경로에 있어도 충돌을 피합니다.
새 태스크용 worktree는 기본적으로 저장소 바깥의 ~/.tmux-worktrees/<repo-name-hash>/ 아래에 생성됩니다.