카테고리

CLAUDE CODE

Zellij로 Claude Code SSH 환경 업그레이드 — tmux에서 갈아탄 이유

2026-04-08

Treeru

이전에 tmux + Claude Code SSH 세션 관리를 다뤘습니다. tmux는 오랫동안 잘 써왔지만, 어느 시점부터 zellij로 전환했습니다. 설치와 설정 모두 간단하고, Claude Code 워크플로우에서 체감 차이가 분명히 있습니다.

이 글에서는 zellij 설치부터 자동화 스크립트, Windows에서의 원클릭 접속, 그리고 실제로 겪은 버그 사례까지 전부 공유합니다.

zellij 0.44.1

사용 버전

5분

서버당 설치 시간

원클릭

Windows bat 접속

Rust

메모리 안전 보장

왜 터미널 멀티플렉서가 필요한가

Claude Code는 터미널에서 동작하는 AI 코딩 도구입니다. SSH로 원격 서버에 접속해 사용할 때, 연결이 끊기면 작업 중이던 세션이 그대로 날아갑니다.

노트북 뚜껑 닫음 → SSH 끊김 → Claude Code 세션 소멸

와이파이 잠깐 끊김 → SSH timeout → 진행 중 작업 소실

터미널 창 실수로 닫음 → 컨텍스트 포함 전부 초기화

터미널 멀티플렉서(tmux, zellij)를 쓰면 세션이 서버 프로세스로 계속 남아 있습니다. SSH가 끊겨도 서버 쪽 세션은 살아있고, 재접속하면 그대로 이어서 작업할 수 있습니다.

# 기존 (SSH 끊기면 끝)
Windows Terminal → SSH → Claude Code 실행

# zellij 적용 후 (SSH와 무관하게 세션 유지)
Windows Terminal → SSH → zellij 세션 → Claude Code 실행

Zellij 설치

바이너리를 직접 받는 방식이 가장 간단합니다. 패키지 매니저 의존성 없이 어느 리눅스 서버에서도 동일하게 작동합니다.

# x86_64 리눅스 기준 (v0.44.1)
curl -sL https://github.com/zellij-org/zellij/releases/download/v0.44.1/zellij-x86_64-unknown-linux-musl.tar.gz \
  | tar xz -C /usr/local/bin/

# sudo 권한이 없는 경우 사용자 디렉토리에 설치
mkdir -p ~/.local/bin
curl -sL https://github.com/zellij-org/zellij/releases/download/v0.44.1/zellij-x86_64-unknown-linux-musl.tar.gz \
  | tar xz -C ~/.local/bin/

설치 후 확인:

zellij --version
# zellij 0.44.1

z 단축 명령 등록

매번 zellij 전체를 치는 것은 번거롭습니다. ~/.bashrc에 alias 한 줄을 추가합니다.

alias z="zellij"

이후 자주 쓰는 명령이 짧아집니다:

z           # zellij 실행
z ls        # 세션 목록
z a 세션명  # 세션 attach
z k 세션명  # 세션 kill

zj 자동 접속 스크립트

세션이 있으면 attach, 없으면 새로 만드는 스크립트입니다. SSH로 서버에 들어왔을 때 이 스크립트 하나만 실행하면 바로 작업 환경으로 복귀할 수 있습니다.

동작 방식

세션이 이미 있으면 → attach (작업 이어가기)

세션이 없으면 → 새로 생성

세 번째 인자에 3을 넣으면 → 3분할 레이아웃 적용

~/.local/bin/zj로 저장:

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

# zellij 경로 자동 탐색
if command -v zellij &>/dev/null; then
    ZJ=zellij
elif [ -x "$HOME/.local/bin/zellij" ]; then
    ZJ="$HOME/.local/bin/zellij"
elif [ -x /usr/local/bin/zellij ]; then
    ZJ=/usr/local/bin/zellij
else
    echo "zellij not found"; exit 1
fi

LAYOUT_FILE="$HOME/.config/zellij/layouts/three.kdl"

cd "$DIR"

if $ZJ list-sessions 2>/dev/null | grep -q "$SESSION"; then
    $ZJ attach "$SESSION"
else
    if [ "$PANES" = "3" ] && [ -f "$LAYOUT_FILE" ]; then
        $ZJ -s "$SESSION" -n "$LAYOUT_FILE"
    else
        $ZJ -s "$SESSION"
    fi
fi

chmod +x ~/.local/bin/zj

인자	설명	기본값
첫 번째	세션명	`ai`
두 번째	시작 디렉토리	`~/ai`
세 번째	3 입력 시 3분할 레이아웃	`1 (단일)`

3분할 레이아웃 설정

Claude Code + 빌드 로그 + 수동 작업을 한 화면에 배치합니다. zellij 레이아웃은 KDL 형식으로 정의합니다.

~/.config/zellij/layouts/three.kdl:

layout {
    pane split_direction="vertical" {
        pane
        pane
        pane
    }
}

split_direction 주의

zellij에서 split_direction="vertical"은 가로 분할(위아래로 쌓기)입니다. 이름과 동작이 반대입니다. 세로 3분할(좌우로 나누기)을 원하면 split_direction="horizontal"을 써야 합니다.

Windows bat 파일로 원클릭 접속

Windows Terminal에서 SSH 접속 → zellij 세션 자동 복귀를 한 번에 처리하는 bat 파일입니다. 서버마다 파일을 하나씩 만들어두면, 더블클릭 한 번으로 바로 작업 환경에 들어갈 수 있습니다.

@echo off
wt nt cmd /k ssh -t 서버별칭 "/home/유저/.local/bin/zj 세션명 ~/프로젝트폴더 3"

실제 적용 예:

@echo off
wt nt cmd /k ssh -t myserver "/home/user/.local/bin/zj dev ~/project 3"

wt nt 명령 설명

wt nt는 Windows Terminal의 새 탭으로 여는 명령입니다. 기존 터미널 창을 유지하면서 새 탭에 해당 서버 세션이 열립니다. 서버가 5대면 bat 파일 5개, 각각 더블클릭이면 모든 서버 작업 환경에 즉시 접근 가능합니다.

알려진 버그: -s + --layout 조합 문제

zellij 0.44.1 기준으로, 세션명과 레이아웃을 동시에 지정할 때 조합에 따라 동작이 달라집니다.

# 안 됨 — 세션은 만들어지는데 레이아웃이 적용 안 됨
zellij -s mysession --layout three

# 됨 — 세션명 + 레이아웃 동시 적용
zellij -s mysession -n three

핵심 포인트

--layout 대신 -n(--new-session-with-layout)을 써야 합니다. 이걸 모르면 “pane이 1개만 나오는데 레이아웃 파일이 문제인가?”라는 시행착오를 하게 됩니다. 위의 zj 스크립트는 -n을 사용하도록 작성되어 있습니다.

SSH PATH 문제와 해결

SSH로 명령을 직접 실행하면(ssh server "command") 비로그인 셸이 열립니다. 이 경우 ~/.bashrc의 alias나 PATH가 적용되지 않아서, zj나 zellij 명령이 “command not found”가 됩니다.

스크립트에서 절대 경로 탐색

zj 스크립트 내부에서 zellij 위치를 자동 탐색하는 로직이 포함되어 있습니다

bat 파일에서 절대 경로로 호출

/home/user/.local/bin/zj 처럼 경로를 명시하면 PATH 문제와 무관하게 실행됩니다

tmux에서 zellij로 갈아탄 이유 4가지

tmux를 오래 쓰다가 zellij로 전환한 후 체감한 실질적인 차이입니다.

터미널 리사이즈 반응

tmux는 창 크기를 바꾸면 레이아웃이 어긋나거나 반응이 느린 경우가 있습니다. zellij는 리사이즈에 즉각 반응합니다. Claude Code처럼 출력이 많은 프로그램에서 이 차이가 더 잘 느껴집니다. 창을 늘렸는데 내용이 즉시 맞게 재배치되는 것은 작은 차이지만, 하루 종일 쓰다 보면 누적됩니다.

텍스트 복사 방식

tmux는 복사 모드 진입 → 노란 하이라이트 → 단축키로 복사하는 별도 워크플로우가 필요합니다. zellij는 일반 터미널처럼 드래그 → Ctrl+C. Claude Code 출력에서 코드 조각이나 에러 메시지를 복사할 때, 기존 습관 그대로 사용할 수 있습니다.

장시간 안정성

tmux는 여러 세션을 오래 운영하다 보면 간헐적으로 표시 이상이나 세션 상태 문제를 경험할 수 있습니다. zellij는 Rust로 작성되어 메모리 안전성이 언어 수준에서 보장됩니다. 여러 서버에 동시에 띄워두고 하루 종일 써도 특별한 문제가 없었습니다.

Claude Code와의 궁합

세션 복구(SSH 끊김 → 재접속 → 이어서 작업), 동시 작업(Claude Code + 빌드 로그 + 파일 탐색을 한 화면에), 장시간 안정성(하루 종일 띄워두고 써도 문제 없을 것) — 이 세 가지를 tmux보다 안정적으로 충족한다는 것이 전환 이유입니다.

	tmux	zellij
복사 방식	복사 모드 진입 → 단축키	드래그 → Ctrl+C
리사이즈	간헐적 지연	즉각 반응
안정성	간헐적 표시 이상	Rust 메모리 안전
설정 학습 비용	높음 (.tmux.conf)	낮음 (기본값 바로 사용)
언어	C	Rust

자주 쓰는 명령어

CLI 명령어

명령어	설명
`z`	zellij 실행
`z ls`	세션 목록 확인
`z a 세션명`	세션 attach
`z k 세션명`	세션 kill
`z ka`	전체 세션 kill
`z da`	전체 세션 delete

세션 내 단축키

단축키	설명
`Ctrl+p → 방향키`	pane 이동
`Ctrl+n`	새 pane 추가
`Ctrl+t`	새 탭 추가
`Ctrl+q`	zellij 종료 (세션은 유지)

마무리

항목	내용
핵심 가치	SSH 끊겨도 Claude Code 세션 유지 + 원클릭 복귀
도구	zellij 0.44.1 + zj 스크립트 + Windows bat
tmux 대비 장점	리사이즈 반응, 직관적 복사, Rust 기반 안정성
주의사항	-n 플래그 사용 (세션명 + 레이아웃 동시 지정 시)
서버당 설치 시간	5분 이내

tmux가 익숙하다면 굳이 전환할 필요는 없습니다. 다만 SSH + Claude Code 환경에서 복사가 불편하거나 리사이즈 반응이 아쉽다면, zellij를 한 번 써보는 것을 추천합니다. 설치 5분, 그냥 켜면 바로 쓸 수 있습니다.

Treeru

웹 개발, IT 인프라, AI 솔루션 분야의 실무 인사이트를 공유합니다. 기업의 디지털 전환을 돕는 IT 파트너, Treeru입니다.

zellij tmux Claude Code SSH 터미널 세션관리 Linux 서버관리 자동화 Windows Terminal

(4)

4.88/ 5

로그인 하면 댓글을 작성할 수 있습니다.

인프라엔지니어H

2026-04-12

5.0

bat 파일로 서버별 원클릭 접속 구성하는 방식 좋습니다. 저도 서버 8대인데 하나씩 만들어둬야겠어요. SSH PATH 문제도 절대 경로로 해결한 거 깔끔합니다.

프론트엔드J

2026-04-11

4.5

split_direction이 이름과 반대로 동작하는 건 진짜 헷갈리네요. vertical이 가로 분할이라니... 주의사항 감사합니다.

DevOps_M

2026-04-10

5.0

-s와 --layout 동시 사용 버그 때문에 30분 삽질한 적 있습니다. -n 플래그로 해결되는 거였군요. 이 글 먼저 봤으면 시간 아꼈을 텐데.