Tmux + Claude Code — SSH 끊겨도 AI가 계속 일하는 환경 만들기

Claude Code를 SSH로 원격 서버에서 쓰다 보면 반드시 마주치는 문제가 있습니다. 네트워크가 끊기면 Claude 세션도 같이 죽습니다.노트북 뚜껑을 닫거나, 잠깐 와이파이가 끊기거나, Windows Terminal 창을 실수로 닫으면 그때까지 진행하던 작업이 전부 사라집니다. 재실행하면 컨텍스트도 초기화됩니다. tmux를 사이에 끼우면 이 문제가 해결됩니다. SSH 연결과 무관하게 세션이 서버에 남아 있고, 다시 접속하면 떠났던 자리 그대로 이어서 작업할 수 있습니다. 이 글에서는 실제로 여러 대 서버에 배포해서 쓰고 있는 tmux 설정과 자동화 스크립트를 전부 공개합니다.

SSH 끊김 = Claude 작업 소멸

기존 방식의 흐름은 단순합니다.

Windows Terminal → SSH 접속 → claude 실행 → 작업

이 구조에서 SSH 연결은 프로세스 생명주기와 직결됩니다. SSH 세션이 끊기는 순간 그 안에서 실행 중이던 모든 프로세스에 SIGHUP 신호가 전달되고, claude 프로세스도 종료됩니다. 진행 중이던 파일 수정이나 분석 작업이 중간에 끊립니다.

오래 걸리는 작업일수록, 그리고 서버 대수가 많을수록 이 문제가 자주 발생합니다. 대규모 리팩토링이나 코드 분석처럼 Claude가 여러 파일을 순서대로 처리해야 하는 작업은 중간에 끊기면 다시 처음부터 지시해야 합니다.

tmux가 해결하는 방식

tmux는 터미널 멀티플렉서입니다. 핵심 개념은 하나입니다. 터미널 프로세스를 SSH 연결과 분리합니다.

Windows Terminal → SSH 접속 → tmux 세션 → Claude 실행

tmux 세션은 SSH 연결이 아닌 서버 프로세스로 살아있습니다. SSH가 끊겨도 tmux 세션은 서버에 그대로 남아 있습니다. 다시 SSH로 접속해서 tmux attach를 실행하면 Claude가 작업하던 그 화면이 그대로 나타납니다.

언제 tmux를 쓰고 언제 안 쓰는가

tmux가 항상 필요한 것은 아닙니다. 작업 성격에 따라 구분해서 씁니다.

별도 alias도 구분해서 씁니다. c는 Claude Code 즉시 실행, cc는 대화 히스토리 조회용입니다.

alias c="command claude --dangerously-skip-permissions"
alias cc="claude-history"

.tmux.conf 전체 설정

아래는 실제로 배포해서 쓰고 있는 ~/.tmux.conf 전체 내용입니다. 각 항목마다 이유가 있습니다. 특히 escape-time은 아래 시행착오 섹션에서 자세히 다룹니다.

set -g default-terminal "xterm-256color"
set -sg escape-time 50
set -g history-limit 100000
set -g set-clipboard on
set -g allow-passthrough off
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on
set -g mouse on
set -g status-left '[#S] '
set -g status-right '%H:%M %Y-%m-%d'
set -g status-style 'bg=colour235,fg=colour250'
setw -g monitor-activity on
set -g visual-activity off

tmux-claude 자동화 스크립트

매번 세션 생성 → claude 실행 → 패널 분할을 수동으로 하는 것은 번거롭습니다. 아래 스크립트를 /usr/local/bin/tmux-claude에 배치하면 하나의 명령으로 원하는 환경이 만들어집니다. 경로를 /usr/local/bin/으로 선택한 이유는 SSH 명령 직접 실행 시 .bashrc가 로드되지 않아도 시스템 PATH에서 찾을 수 있기 때문입니다. (아래 시행착오 참고)

#!/bin/bash
SESSION="${1:-ai}"
DIR="${2:-~/ai}"
PANES="${3:-1}"

if tmux has-session -t "$SESSION" 2>/dev/null; then
    tmux attach -t "$SESSION"
else
    tmux new -s "$SESSION" -d -c "$DIR"
    tmux send-keys -t "$SESSION" 'c' Enter
    for ((i=2; i<=PANES; i++)); do
        tmux split-window -h -t "$SESSION" -c "$DIR"
        tmux send-keys -t "$SESSION" 'c' Enter
        tmux select-layout -t "$SESSION" even-horizontal
    done
    tmux attach -t "$SESSION"
fi

사용 예시

# 기본 (세션명 ai, AI 워크스페이스 디렉토리, 1패널)
tmux-claude

# 세션명 지정
tmux-claude dev ~/project

# 3패널 분할 (Claude 3개 동시 실행)
tmux-claude ai ~/ai 3

Windows에서 원클릭 실행

Windows Terminal에서 bat 파일로 SSH 접속 + tmux 세션 진입을 한 번에 처리할 수 있습니다. 자주 쓰는 서버별로 bat 파일을 만들어두면 아이콘 더블클릭 하나로 Claude 환경이 열립니다.

단일 패널

@echo off
wt nt cmd /k ssh -t 메인서버 "tmux-claude ai ~/ai"

3패널 분할 (Claude 3개 동시 실행)

@echo off
wt nt cmd /k ssh -t 메인서버 "tmux-claude ai ~/ai 3"

필수 명령어 정리

세션 관리

세션 안에서 (Ctrl+b 누른 후 손 떼고 다음 키)

시행착오 기록

설정 과정에서 겪은 문제들을 기록합니다. 대부분 검색해도 나오지 않는 조합별 문제들이라 처음 맞닥뜨리면 원인 파악에 시간이 걸립니다.

1. OSC 색상 코드 문자열 출력 문제

시도했으나 실패한 방법들

# 시도 1: screen-256color + terminal-overrides Tc → 실패
set -g default-terminal "screen-256color"

# 시도 2: tmux-256color + focus-events 제거 → 실패
set -g default-terminal "tmux-256color"

# 시도 3: terminal-overrides 전부 제거 → 실패

최종 해결

set -g default-terminal "xterm-256color"
set -sg escape-time 50        # 핵심: 0이면 안 됨
set -g allow-passthrough off  # 패스스루 차단

2. Claude Code 설치 스크립트 sh vs bash 문제

# 이렇게 하면 안 됩니다
curl -fsSL https://claude.ai/install.sh | sh

# 반드시 bash로 지정
curl -fsSL https://claude.ai/install.sh | bash

3. SSH non-interactive 모드에서 명령어 못 찾음

4. tmux.conf 수정 후 변화 없음

5. Claude 버전 우선순위 충돌

6. 세션 이름에 한글 또는 특수문자 사용

다수 서버 일괄 배포 방법

여러 대 서버를 운영하는 경우 각 서버에 개별 접속해서 설정하는 것은 비효율적입니다. scp와 ssh를 반복문으로 묶어서 백그라운드 병렬 실행하면 전체 배포가 몇 초 안에 끝납니다.

.tmux.conf 배포

for server in 서버1 서버2 서버3; do
  scp -q ~/.tmux.conf ${server}:~/.tmux.conf &
done
wait

tmux-claude 스크립트 배포

for server in 서버1 서버2 서버3; do
  scp -q /usr/local/bin/tmux-claude ${server}:/tmp/tmux-claude
  ssh ${server} "sudo cp /tmp/tmux-claude /usr/local/bin/tmux-claude && sudo chmod +x /usr/local/bin/tmux-claude" &
done
wait

마무리

tmux + Claude Code 조합은 설정이 단순한 만큼 효과가 즉각적입니다. SSH 끊김에 대한 불안 없이 긴 작업을 맡길 수 있고, 멀티패널로 Claude 여러 개를 동시에 띄워 독립적인 작업을 병렬 처리하는 것도 가능합니다.

설정에서 가장 주의할 점은 escape-time입니다. 많은 가이드에서 응답 속도를 위해 0으로 설정하라고 하지만, Windows Terminal과 조합하면 OSC 응답 문자열이 화면에 출력되는 문제가 생깁니다. 50ms가 적절한 값입니다.

tmux를 쓰면서 가장 달라진 점은 “지금 당장 이 작업을 끝내야 한다”는 압박이 없어졌다는 것입니다. 자리를 떠야 할 때 Ctrl+b → d로 빠져나오면 그만입니다. 다시 돌아왔을 때 Claude는 그 자리에서 기다리고 있습니다.