Tmux 빠른 시작 가이드

Tmux 터미널 멀티플렉서를 처음부터 배우기: 기본 개념, 자주 쓰는 명령어, Claude Code와의 심층 통합

서론

Adoption of tools like Tmux has surged, largely due to the agent team workflows found in command-line coding agent products like Claude Code.

Towards Data ScienceA beginner's guide to Tmux

이동

Claude Code의 Agent Teams를 사용해 본 적이 있거나 여러 Claude 인스턴스를 동시에 실행하고 싶다면, Tmux는 거의 필수 도구입니다. Tmux를 사용하면 하나의 터미널 창에서 여러 세션을 실행할 수 있고, 터미널을 닫아도 세션이 백그라운드에서 계속 실행되며, Claude가 Tmux 내에서 자동으로 여러 Agent를 생성하고 관리할 수 있습니다.

이 튜토리얼은 Claude Code 사용자를 위해 설계되었으며, Tmux 기초 지식과 Claude Code와의 통합 기법을 모두 다룹니다.

Tmux 이해하기

Tmux (Terminal Multiplexer)

터미널 멀티플렉서로, 하나의 터미널 창에서 여러 터미널 세션을 생성하고 관리할 수 있습니다. 핵심 기능은 세션 지속성입니다—연결이 끊어져도 세션이 계속 실행되며, 다시 연결하면 이전 상태로 복원할 수 있습니다.

출처: Tmux Wiki이동

Tmux의 세 가지 핵심 개념:

┌─────────────────────────────────────────────────────────┐
│                    Session（세션）                        │
│  ┌─────────────────────────────────────────────────────┐│
│  │                 Window（윈도우）                      ││
│  │  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ ││
│  │  │   Pane 1     │  │   Pane 2     │  │  Pane 3   │ ││
│  │  │  (Claude 1)  │  │  (Claude 2)  │  │  (Logs)   │ ││
│  │  │              │  │              │  │           │ ││
│  │  │              │  │              │  │           │ ││
│  │  └──────────────┘  └──────────────┘  └───────────┘ ││
│  └─────────────────────────────────────────────────────┘│
│  Window 1: Development    Window 2: Testing             │
└─────────────────────────────────────────────────────────┘

개념	비유	설명
Session	워크스페이스	최상위 컨테이너로, 연결이 끊어져도 계속 실행됩니다
Window	브라우저 탭	하나의 세션에 여러 윈도우를 포함할 수 있습니다
Pane	화면 분할	하나의 윈도우를 여러 패널로 분할할 수 있습니다

설치 및 기본 사항

Tmux 설치

# macOS
brew install tmux

# Ubuntu/Debian/WSL
sudo apt-get install tmux

# CentOS/RHEL
sudo yum install tmux

설치 확인:

tmux -V
# 출력 예시: tmux 3.6a

접두사 키

Tmux의 모든 명령은 접두사 키로 시작하며, 기본값은 Ctrl+B입니다.

명령 입력 방법:

Ctrl+B를 누릅니다 (놓지 마세요)
놓은 후 명령 키를 누릅니다

예를 들어, 윈도우 분할: Ctrl+B 후 %를 누릅니다

자주 쓰는 명령어 빠른 참조

세션 관리

명령어	설명
`tmux`	새 세션 생성
`tmux new -s name`	이름이 지정된 세션 생성
`tmux ls`	모든 세션 목록 표시
`tmux attach -t name`	세션에 연결
`tmux kill-session -t name`	세션 종료
`Ctrl+B d`	현재 세션 분리 (백그라운드 실행)

윈도우 관리

단축키	설명
`Ctrl+B c`	새 윈도우 생성
`Ctrl+B n`	다음 윈도우
`Ctrl+B p`	이전 윈도우
`Ctrl+B 0-9`	지정된 윈도우로 전환
`Ctrl+B ,`	현재 윈도우 이름 변경
`Ctrl+B &`	현재 윈도우 닫기

패널 관리

단축키	설명
`Ctrl+B %`	수직 분할 (좌우)
`Ctrl+B "`	수평 분할 (상하)
`Ctrl+B 방향키`	패널 간 이동
`Ctrl+B x`	현재 패널 닫기
`Ctrl+B z`	패널 최대화/복원
`Ctrl+B {`	패널 왼쪽으로 이동
`Ctrl+B }`	패널 오른쪽으로 이동

기타 자주 사용하는 기능

단축키	설명
`Ctrl+B [`	복사 모드 진입 (스크롤 가능)
`q`	복사 모드 종료
`Ctrl+B ?`	모든 단축키 표시

Claude Code와의 통합

Claude Code에 Tmux가 필요한 이유

Agent Teams의 Split-pane 모드: 각 Teammate가 독립된 패널에 표시됩니다
백그라운드 실행: 터미널을 닫아도 작업이 계속 실행됩니다
세션 지속성: 연결이 끊어져도 다시 연결하면 완전한 컨텍스트가 복원됩니다
다중 인스턴스 관리: 여러 Claude 세션을 동시에 실행할 수 있습니다

기본 사용법: Claude 백그라운드 실행

# tmux에서 Claude 시작
tmux new -s claude-work
claude

# 세션 분리 (Claude 계속 실행)
# Ctrl+B d

# 나중에 다시 연결
tmux attach -t claude-work

--tmux 매개변수 사용

Claude Code는 Tmux 통합을 기본 지원합니다:

# 새 tmux 세션에서 Claude 시작
claude --tmux

# worktree와 함께 사용
claude -w feature-auth --tmux

이 명령은 자동으로:

새 tmux 세션을 생성합니다
그 안에서 Claude Code를 시작합니다
세션 이름을 claude-{랜덤ID}로 지정합니다

Agent Teams의 Tmux 모드

Agent Teams는 split-pane 표시 모드를 사용할 수 있으며, 각 Teammate가 독립된 패널에서 실행됩니다:

// settings.json
{
  "teammateMode": "tmux"
}

또는 명령줄을 통해:

claude --teammate-mode tmux

효과:

┌─────────────────────────────────────────────────────────┐
│                    Team Lead                             │
├─────────────────┬─────────────────┬─────────────────────┤
│   Teammate 1    │   Teammate 2    │    Teammate 3       │
│   Security      │   Performance   │    Testing          │
│                 │                 │                     │
└─────────────────┴─────────────────┴─────────────────────┘

실용적인 설정

권장 ~/.tmux.conf

~/.tmux.conf를 생성하거나 편집합니다:

# Ctrl+A를 접두사 키로 사용 (누르기 더 편함)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# 마우스 지원 활성화
set -g mouse on

# 히스토리 버퍼 증가 (Claude 출력이 많음)
set -g history-limit 50000

# vim 스타일 패널 탐색
bind h select-pane -L
bind j select-pane -D
bind k select-pane -U
bind l select-pane -R

# 더 직관적인 분할 단축키
bind | split-window -h
bind - split-window -v

# 설정 빠른 리로드
bind r source-file ~/.tmux.conf \; display "Config reloaded!"

# 256색 지원
set -g default-terminal "screen-256color"
set -ga terminal-overrides ",*256col*:Tc"

# 윈도우 번호를 1부터 시작 (0은 너무 멀리 있음)
set -g base-index 1
setw -g pane-base-index 1

# 상태 표시줄 최적화
set -g status-position bottom
set -g status-left-length 40
set -g status-right-length 60

설정 리로드:

tmux source-file ~/.tmux.conf

Claude Code 전용 설정

Claude Code에 최적화된 설정:

# Claude 세션 팝업 단축키
bind -r y run-shell '\
  SESSION="claude-$(echo #{pane_current_path} | md5sum | cut -c1-8)"; \
  tmux has-session -t "$SESSION" 2>/dev/null || \
  tmux new-session -d -s "$SESSION" -c "#{pane_current_path}" "claude"; \
  tmux display-popup -w80% -h80% -E "tmux attach-session -t $SESSION"'

이 설정의 효과:

Ctrl+A y를 눌러 Claude 팝업을 엽니다
각 디렉토리마다 독립된 Claude 세션이 있습니다
팝업을 닫아도 세션은 계속 실행됩니다
다시 열면 이전 대화가 복원됩니다

일반적인 워크플로

워크플로 1: 다중 프로젝트 병렬 작업

# 각 프로젝트에 독립 세션 생성
tmux new -s project-a
# 안에서 Claude 시작
claude -w feature-x

# 분리 후 다른 세션 생성
# Ctrl+B d
tmux new -s project-b
claude -w bugfix-y

# 세션 간 전환
tmux switch -t project-a
tmux switch -t project-b

# 또는 모든 세션을 나열하여 선택
# Ctrl+B s

워크플로 2: 개발 대시보드

다중 패널 개발 환경 생성:

# 세션 생성
tmux new -s dev

# 세 개의 패널로 분할
# Ctrl+B % (수직 분할)
# Ctrl+B " (오른쪽 수평 분할)

# 패널 레이아웃:
# ┌───────────┬───────────┐
# │  Claude   │   Logs    │
# │           ├───────────┤
# │           │   Tests   │
# └───────────┴───────────┘

# 첫 번째 패널에서 Claude 실행
claude

# 두 번째 패널로 전환 (Ctrl+B 오른쪽 화살표)
tail -f logs/app.log

# 세 번째 패널로 전환
npm test -- --watch

워크플로 3: 원격 개발

Tmux의 가장 강력한 기능은 세션 지속성으로, 특히 SSH 원격 개발에 적합합니다:

# 원격 서버에 연결
ssh user@server

# tmux 세션 생성
tmux new -s remote-claude

# Claude 시작
claude

# SSH 연결 끊기 (Claude 계속 실행)
# Ctrl+B d
exit

# 나중에 다시 연결
ssh user@server
tmux attach -t remote-claude
# Claude 세션 완전 복원

워크플로 4: Agent Teams 모니터링

tmux를 사용하여 Agent Teams의 모든 Teammate를 모니터링합니다:

# Claude를 tmux 모드로 시작
claude --teammate-mode tmux

# Agent Team 생성
# "agent team을 만들어서 코드를 리뷰..."

# 화면이 자동으로 분할되며, 각 Teammate마다 하나의 패널이 생성됩니다
# 다른 패널을 클릭하여 해당 Teammate와 직접 소통할 수 있습니다

문제 해결

자주 발생하는 문제

문제	해결 방법
색상이 올바르게 표시되지 않음	`TERM=xterm-256color`를 확인하세요
마우스가 작동하지 않음	설정에 `set -g mouse on`을 추가하세요
복사/붙여넣기 문제	복사 모드에서 `Enter`를 사용하여 복사하세요
세션이 사라짐	`tmux ls`를 확인하세요, 시스템 재시작일 수 있습니다

고아 세션 정리

Claude Code는 때때로 정리되지 않은 tmux 세션을 남길 수 있습니다:

# 모든 세션 나열
tmux ls

# 특정 세션 종료
tmux kill-session -t session-name

# 모든 세션 종료 (주의!)
tmux kill-server

iTerm2 사용자

macOS의 iTerm2를 사용하는 경우, 네이티브 통합을 활용할 수 있습니다:

# iTerm2의 tmux 통합 모드 사용
tmux -CC

# 또는 Claude Code에서
claude --teammate-mode tmux

iTerm2는 자동으로 tmux 패널을 네이티브 탭과 화면 분할로 변환합니다.

사용 후기

Tmux가 필요한 경우

시나리오	Tmux 필요 여부
간단한 일회성 Claude 대화	불필요
장시간 실행되는 작업	필요
Agent Teams	강력 추천
원격 개발	필수
다중 프로젝트 병렬 작업	추천

최소 설정

설정을 복잡하게 하고 싶지 않다면, 다음 몇 가지 명령만 기억하면 됩니다:

# 세션 생성
tmux new -s work

# 분리 (백그라운드 실행)
Ctrl+B d

# 다시 연결
tmux attach -t work

# 패널 분할
Ctrl+B %    # 좌우 분할
Ctrl+B "    # 상하 분할

# 패널 전환
Ctrl+B 방향키

Claude Code와의 최적 조합

Worktree + Tmux: 각 worktree를 독립된 tmux 세션에서 실행합니다
```
claude -w feature-auth --tmux
```
Agent Teams + Tmux: 모든 Teammate를 시각적으로 관리합니다
```
claude --teammate-mode tmux
```

장기 작업 + 분리: 시작 후 분리하고, 나중에 돌아와서 확인합니다

# 시작
tmux new -s migration
claude
# "데이터베이스 마이그레이션 실행..."
# Ctrl+B d

# 몇 시간 후
tmux attach -t migration

마무리

Tmux는 Claude Code를 효율적으로 사용하기 위한 핵심 도구이며, 특히 다음과 같은 시나리오에서 중요합니다:

핵심	설명
지속성	연결이 끊어져도 세션이 유실되지 않습니다
병렬 처리	여러 Claude 인스턴스를 동시에 관리합니다
시각화	Agent Teams의 split-pane 표시를 지원합니다

세 가지 핵심 명령만으로 시작할 수 있습니다:

tmux new -s name 세션 생성
Ctrl+B d 세션 분리
tmux attach -t name 다시 연결

관련 읽을거리:

Claude Agent Teams 완벽 가이드 — Agent Teams는 split-pane 모드를 위해 Tmux가 필요합니다
Claude Worktree 완벽 가이드 — Worktree는 Tmux와 함께 백그라운드에서 실행할 수 있습니다

참고 자료:

동영상 튜토리얼:

Tmux Basics Tutorial — Tmux 기초 입문
Tmux + Claude Code Workflow — Claude Code 통합 워크플로
Advanced Tmux Configuration — 고급 설정 기법