tmux 사용법: Claude Code 원격 작업과 worktree 관리

구분해야 할 것은 실제로 작업을 실행하는 머신입니다. tmux는 연결이 끊겨도 터미널 세션을 유지합니다. 하지만 잠든 노트북에서 연산을 계속하거나, 꺼진 서버를 살려 두거나, 비정상 종료된 Claude 프로세스를 다시 시작하지는 못합니다. Anthropic도 SSH 연결이 끊긴 뒤에도 원격 Claude 세션을 유지해야 한다면 tmux 또는 screen을 사용하라고 명시적으로 권장합니다. Anthropic Remote Control 문서.

tmux 사용법의 시작: 공식 문서의 설정 적용하기

설정은 Claude Code가 실행되는 머신에 적용합니다. 원격으로 작업한다면 원격 호스트의 ~/.tmux.conf를 수정해야 합니다. 필요하면 해당 호스트의 패키지 관리자로 tmux를 설치하고, 다음 단계로 넘어가기 전에 그 호스트에서 tmux -V와 claude --version을 확인합니다.

아래 내용을 ~/.tmux.conf에 추가합니다. 처음 세 줄은 Anthropic 공식 문서에 나오는 설정입니다. 주석 처리된 마우스 설정은 선택 사항이며 Anthropic의 필수 요건이 아닙니다.

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

# Optional preference: enable mouse interaction in tmux.
# set -g mouse on

Passthrough는 알림과 진행 상태 업데이트가 tmux 바깥의 터미널까지 전달되도록 합니다. 확장 키 설정은 tmux가 Shift+Enter와 Enter를 구분할 수 있게 합니다. 실행 중인 tmux 서버에 설정을 적용하려면 tmux source-file ~/.tmux.conf를 실행합니다. 새 서버는 시작할 때 이 파일을 읽습니다. Anthropic 터미널 설정 문서.

아직 tmux 서버가 없다면 아래 안내에 따라 첫 세션을 만든 뒤 설정을 다시 불러오는 명령을 실행합니다. 초기 구성에는 서드파티 플러그인을 넣지 않습니다. 이 워크플로에 필수인 플러그인은 없습니다.

worktree마다 이름을 붙인 세션 따로 만들기

Git worktree는 저장소 이력을 공유하면서도 파일과 브랜치를 따로 갖는 또 하나의 체크아웃입니다. tmux 세션은 이름으로 구분하는 터미널 창 묶음이고, 패널은 창을 나눈 영역입니다. worktree를 작업대, tmux를 나갔다가 다시 들어올 수 있는 방이라고 생각하면 됩니다. Anthropic worktree 가이드.

세션 이름만 보고도 어느 체크아웃에 들어가는지 알 수 있도록 이름 규칙을 맞춥니다. 아래는 이 글에서 제안하는 구성이며, Claude Code의 기본 구성은 아닙니다.

아래 초기 설정 예제는 ~/src/project에 기존 저장소가 있고, 커밋이 하나 이상 있으며, 사용할 브랜치·디렉터리·세션 이름이 아직 쓰이지 않는다는 전제입니다. dev@devbox와 프로젝트 경로는 자신의 환경에 맞게 바꿉니다. 노트북에서 tmux 밖의 일반 셸을 열고 시작합니다. worktree 명령은 Anthropic의 수동 관리 절차를 따르며, 이름을 붙인 세션 구성은 이 가이드가 제안하는 방식입니다.

ssh dev@devbox
cd ~/src/project

git worktree add ../project-feature-a -b feature-a
git worktree add ../project-bugfix -b bugfix

tmux new-session -d -s cc-feature-a -n claude -c "$HOME/src/project-feature-a"
tmux new-session -d -s cc-bugfix -n claude -c "$HOME/src/project-bugfix"

tmux attach-session -t cc-feature-a
# Now inside the feature worktree's tmux shell:
claude

SSH 연결 후 나머지 명령은 원격 호스트에서 입력합니다. 분리된 상태로 만든 두 세션에는 처음에는 셸만 실행되어 있습니다. 한 세션에 접속해 claude를 실행하면 일반적인 초기 설정 프롬프트를 포함해 코딩 세션이 화면에 나타납니다. 두 번째 작업도 시작하려면 현재 세션에서 분리한 뒤 cc-bugfix에 접속해 그곳에서 claude를 실행합니다.

각 worktree에는 의존성과 필요한 로컬 설정 등 프로젝트 환경을 별도로 준비해야 합니다. Claude에 파일 수정을 맡기기 전에 디렉터리와 브랜치를 확인합니다. Anthropic worktree 수동 관리 절차.

기능 개발용 체크아웃에 테스트 셸을 추가하고 싶다면 호스트의 셸에서 tmux new-window -t cc-feature-a -n checks -c "$HOME/src/project-feature-a"를 실행합니다. 검증 작업은 해당 작업의 세션 안에 둡니다. 기본 체크아웃을 두 에이전트가 함께 쓰는 임시 작업 디렉터리로 사용하지 않습니다.

Codex도 사용한다면 Codex CLI worktree 가이드에서 해당 툴의 워크플로를 따로 다룹니다.

노트북을 닫아도 이어서 작업하기: 세션 분리와 SSH 재접속

tmux의 기본 접두 키를 사용한다면 Ctrl+B를 누르고 두 키에서 손을 뗀 다음 D를 누릅니다. 클라이언트가 세션에서 분리되고 원격 셸로 돌아옵니다. 이제 SSH 연결을 끊어도 됩니다. Claude는 세션 안에서 계속 실행되도록 둡니다.

돌아와서는 ssh dev@devbox, tmux list-sessions, tmux attach-session -t cc-feature-a 순서로 실행합니다. 같은 원격 호스트와 사용자 계정을 사용해야 합니다. 노트북에서 ssh -t dev@devbox 'tmux attach-session -t cc-feature-a'를 실행하면 한 명령으로 같은 작업을 할 수 있습니다.

이 키 조합은 기본 접두 키를 기준으로 합니다. 이미 바꿨다면 자신이 설정한 접두 키를 사용합니다. tmux 안에서는 다른 tmux 클라이언트를 중첩해서 실행하지 말고 세션을 전환합니다.

세션에 다시 접속하면 기존 터미널 프로세스로 연결됩니다. 그 프로세스가 이미 종료됐다면 대화 복구는 별개의 작업입니다. claude --continue는 현재 디렉터리의 가장 최근 대화를 이어 가고, claude --resume은 대화를 고르는 화면을 엽니다. 어느 명령도 원래 프로세스를 계속 실행해 두는 일을 대신하지는 못합니다. Anthropic 세션 워크플로.

휴대폰이나 브라우저에서 접속하려면 Claude Code Remote Control을 참고합니다. 이 경우에도 실제 실행은 호스트에서 이루어지므로 호스트가 켜져 있어야 합니다. Anthropic Remote Control.

작업 간 조율이 필요할 때 Claude Code 에이전트 팀 추가하기

에이전트 팀은 실험적 기능이며 기본적으로 꺼져 있습니다. tmux 셸에서 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude --teammate-mode tmux를 실행해 새로운 대화형 리드 세션을 시작합니다. 환경 변수는 이번 실행에서 팀 기능을 켜고, 플래그는 분할 패널을 선택합니다. Anthropic 에이전트 팀 설정.

현재 기본값은 in-process입니다. auto는 tmux 안에서 분할 패널을 사용하고 필요하면 다른 모드로 전환합니다. tmux는 터미널을 감지해 분할 패널 모드를 선택합니다. 설정을 계속 유지하려면 ~/.claude/settings.json의 teammateMode를 사용합니다. 분할 패널에서는 팀원마다 별도의 터미널이 화면에 표시됩니다. Anthropic은 VS Code 통합 터미널, Windows Terminal, Ghostty를 이 모드에서 지원하지 않는 터미널로 명시합니다. Anthropic 표시 모드와 제한 사항.

처음 시험해 본다면 저는 리드에게 다음처럼 범위가 좁은 작업을 맡기겠습니다.

수동으로 시작한 cc-feature-a와 cc-bugfix 세션은 둘 다 tmux 안에 있다는 이유만으로 팀원이 되지 않습니다. 팀 구성은 누가 작업을 배분하고 조사 결과를 종합할지에 관한 별도의 선택입니다. 한 세션 안에서 특정 작업을 집중적으로 위임하려면 Claude Code 서브에이전트가 더 적합합니다.

패널이 나뉘어 있다고 체크아웃까지 분리되는 것은 아닙니다. 독립적으로 파일을 수정하려면 서로 다른 파일을 맡기거나 별도의 worktree를 사용합니다. 팀은 토큰도 더 많이 사용하며, tmux가 그 사용량을 줄여 주지는 않습니다. 다시 접속하면 살아 있는 터미널로 돌아갈 수 있지만, /resume은 프로세스 내부에서 실행되던 팀원을 복원하지 못합니다. Anthropic 팀 운영 안내.

이 구성이 잘 맞는 다섯 가지 작업 상황

저라면 아래 순서로 활용을 검토하겠습니다. 각각 가능한 워크플로를 제안한 것이며, 생산성 향상을 측정했다는 주장은 아닙니다.

자동화를 더하기 전에 작업 중단으로 드는 비용부터 측정합니다. 예를 들어 작업 맥락을 다시 파악하는 데 매번 4분이 걸리고 이런 중단이 일주일에 5번 생긴다면 주당 20분이 듭니다. 이는 가상의 입력값이며 벤치마크 결과가 아닙니다. 자신의 복귀 시간, 설정 시간, 검토 시간을 기록합니다. 그 합계가 줄어들어야 이 워크플로를 쓸 가치가 있습니다. 에이전트를 동시에 더 많이 실행한다고 반드시 이득이 커지는 것은 아닙니다.

이 구성을 바탕으로 만들어 볼 만한 작은 툴 두 가지

더 유망한 쪽은 개발팀용 worktree·세션 런처입니다. 플랫폼 팀은 개발자 전체가 작업 이름, 체크아웃 경로, 접속 명령을 일관되게 사용하도록 하는 데 비용을 지불할 수 있습니다. 최소한의 유용한 버전이라면 worktree를 생성하거나 찾아서 이름에 맞는 tmux 세션을 열고, Claude를 실행하기 전에 브랜치와 경로를 보여 주면 됩니다. 체크아웃을 정리하기 전에는 확인을 받아야 합니다.

2026년 10월 12일에 조회한 DataForSEO의 미국 키워드 추정치에 따르면 “tmux claude code”의 월간 검색량은 480회입니다. 이는 설정에 대한 관심을 보여 주는 제한적인 신호이며 구매자 수가 아닙니다. 짧은 내부 스크립트만으로도 충분할 수 있다는 점이 걸림돌입니다. 유료 제품이라면 반복 작업을 줄여 주는 팀별 설정이나 지원이 필요합니다.

두 번째는 범위가 더 좁은 원격 세션 목록 관리 툴입니다. 소규모 엔지니어링 팀이 승인된 호스트 별칭, 세션 이름, 체크아웃 경로를 한곳에 기록하고 SSH 접속 명령을 복사할 수 있게 하는 제품입니다. 검색과 탐색 기능부터 시작하고, 사용자가 필요로 할 때만 수명 주기 관리 기능을 추가합니다.

같은 DataForSEO 조회에서 미국 월간 검색량은 “claude code remote”가 1,600회, “claude code remote ssh”가 70회로 추정됩니다. 더 넓은 검색어에는 다른 원격 인터페이스를 찾는 사람도 포함되므로, 이것만으로 SSH 제품의 수요가 입증되지는 않습니다. 여기서 걸림돌은 접근 권한 관리입니다. 목록 관리 툴은 각 개발자에게 이미 부여된 호스트 권한을 따라야 합니다. 대시보드를 만들기 전에 원격 근무 중심의 팀을 인터뷰합니다.

실제 사용 중 자주 마주치는 질문

월요일에 바로 해 볼 일은 원격 작업 하나를 골라 worktree와 이름을 붙인 세션을 만드는 것입니다. 작업을 실행해 둔 채 자리를 비우기 전에 세션에서 분리했다가 다시 접속할 수 있는지 확인합니다. 이 과정이 익숙해진 뒤에 두 번째 독립 작업을 추가합니다.

팀 개발 환경에 이 워크플로를 구축해야 한다면, 실서비스용 AI 시스템을 구축하는 저희에게 문의하세요.