tmux 완전 정복 가이드 | 설치부터 AI 에이전트 자동화까지

여러분, 터미널에서 개발하다 보면 실행 중인 서버, 로그, 테스트, AI 코딩 에이전트 세션을 안정적으로 유지하는 게 생산성의 핵심입니다. tmux(Terminal Multiplexer)는 터미널 창을 닫아도 작업 세션을 보존하고, 여러 작업 화면을 하나의 구조로 관리하게 해주는 도구입니다.

tmux는 2007년 Nicholas Marriott이 처음 공개한 오픈소스 터미널 멀티플렉서입니다. 거의 19년 된 오래된 도구죠. 그런데 Claude Code, OpenAI Codex CLI, Gemini CLI처럼 터미널에서 동작하는 코딩 에이전트가 늘어나면서 다시 주목받고 있습니다. 여러 에이전트와 개발 프로세스를 동시에 운영한다면, 제가 보기에 tmux는 단순 편의 도구가 아니라 작업 인프라에 가깝습니다.

이 글에서는 tmux의 핵심 개념부터 필수 단축키 체계, 설정 파일 최적화, 여러 AI 에이전트를 병렬로 운용하는 자동화 워크플로까지 단계별로 정리합니다. 처음 tmux를 접하는 분도 세션, 윈도우, 페인의 차이를 이해하고 바로 실무에 적용할 수 있도록 구성했습니다.

이 글의 핵심 요약

• tmux는 터미널 에뮬레이터가 아닌 터미널 멀티플렉서다: iTerm2·Ghostty·WezTerm 같은 터미널 앱과 달리, tmux는 쉘 세션을 별도의 서버 프로세스로 관리하기 때문에 터미널 창을 닫아도 세션이 살아남는다
• 3계층 구조(세션 → 윈도우 → 페인)를 이해해야 한다: 이 계층 구조가 tmux 모든 단축키와 스크립트의 기반이 된다
• Ctrl+B가 기본 프리픽스(Prefix)이지만 커스터마이징이 권장된다: 실무에서는 Ctrl+Space로 리매핑하거나 Vim 방향키(hjkl)를 연동하면 훨씬 편하다
• 히스토리 리밋 확장과 마우스 모드 활성화는 필수 설정이다: 기본값 2,000줄 히스토리는 개발 서버 로그가 금방 넘쳐나므로 5만 줄 이상으로 늘려야 한다
• tmux 스크립트로 전체 개발 환경을 코드로 정의할 수 있다: 세션·윈도우·페인 생성부터 개발 서버·Claude Code 실행까지 한 줄 명령으로 자동화 가능하다
• send-keys와 capture-pane 명령이 AI 에이전트 연동의 핵심이다: 에이전트가 다른 페인의 로그를 읽어오거나 명령을 전송하는 크로스-페인 통신을 구현한다
• 멀티 에이전트 교차 검증(Cross Verification) 워크플로가 실전 활용의 정수다: Claude Code 팀 리드가 Codex·Gemini CLI 에이전트를 별도 페인에 스폰하여 동일 결과물을 병렬로 검증한다

---

1. 터미널 에뮬레이터 vs 터미널 멀티플렉서: 근본적인 차이

터미널 에뮬레이터란

터미널 에뮬레이터(Terminal Emulator)는 화면을 그려주는 앱입니다. Ghostty, iTerm2, WezTerm, Kitty, Warp, Wezterm처럼 여러분이 평소에 설치해서 쓰는 터미널 앱이 모두 여기에 속합니다. 터미널 에뮬레이터는 실행되는 동안 쉘 프로세스와 직접 연결(attach)되어 있습니다. 이 말은 즉, 앱을 닫으면 쉘과 그 안에서 돌아가던 모든 프로세스도 같이 종료된다는 뜻입니다.

실제로 Claude Code를 실행해 두고 Ghostty 창을 닫으면, 다시 열었을 때 Claude Code 세션은 사라지고 없습니다. 개발 서버 역시 마찬가지입니다.

터미널 멀티플렉서란

터미널 멀티플렉서(Terminal Multiplexer)는 세션을 관리하는 서버입니다. tmux를 실행하면 내부적으로 tmux 서버(daemon)가 백그라운드에서 동작하고, 여러분의 터미널 앱은 이 서버에 붙어(attach) 있는 클라이언트 역할만 합니다.

[터미널 에뮬레이터 구조]
터미널 앱 ──── 쉘 프로세스
     ↓ 앱 종료
쉘도 함께 종료

[tmux 구조]
터미널 앱 ──── tmux 클라이언트 ──── tmux 서버 ──── 쉘 프로세스
     ↓ 앱 종료
클라이언트만 분리(detach), 서버와 쉘은 유지

터미널 앱을 닫아도 tmux 서버와 그 안의 쉘은 그대로 살아있습니다. 나중에 tmux attach만 입력하면 작업하던 상태 그대로 돌아올 수 있습니다. 이것이 tmux의 가장 근본적이고 강력한 특성입니다.

어떤 터미널 에뮬레이터를 써야 할까

tmux는 어떤 터미널 에뮬레이터에서도 동작합니다. tmux 자체가 탭 관리, 화면 분할, 세션 관리를 모두 담당하므로, 터미널 앱은 가볍고 빠른 것을 기준으로 고르면 됩니다.

터미널 에뮬레이터	분류	특징
Ghostty	에뮬레이터	GPU 가속, 낮은 CPU/메모리 사용률, 추천
iTerm2	에뮬레이터	macOS 전통의 강자, 기능 풍부
WezTerm	에뮬레이터	Lua 기반 설정, 크로스 플랫폼
Kitty	에뮬레이터	GPU 가속, 빠른 렌더링
Warp	에뮬레이터	AI 통합 UX, 입문자 친화적
tmux	멀티플렉서	세션 서버, 모든 에뮬레이터와 조합 가능
screen	멀티플렉서	tmux의 전신, 현재는 tmux가 대세

tmux 사용 시 가장 추천하는 터미널은 Ghostty입니다. GPU 기반 렌더링으로 성능이 뛰어나고, CPU·메모리 점유율이 낮아 tmux를 빠르게 구동하기에 최적입니다.

---

2. tmux 3계층 구조: 세션 · 윈도우 · 페인

tmux를 처음 배울 때 가장 먼저 이해해야 하는 것은 3계층 구조입니다. 이 구조를 이해해야 단축키와 스크립트가 전부 맥락 있게 연결됩니다.

Session (세션)
└── Window 0 (윈도우)
│   ├── Pane 0 (페인)  ← 개발 서버
│   └── Pane 1 (페인)  ← Claude Code
└── Window 1 (윈도우)
    ├── Pane 0
    ├── Pane 1
    └── Pane 2

세션 (Session)

세션은 tmux의 최상위 단위입니다. 하나의 프로젝트나 작업 맥락을 대표하는 단위로 사용하면 좋습니다. 예를 들어 frontend, backend, claude 같은 이름을 붙여두면 여러 프로젝트를 동시에 운영할 때 구분이 쉽습니다.

• tmux를 처음 실행하면 세션 하나가 자동으로 생성됩니다
• 여러 세션을 동시에 운영할 수 있습니다
• 각 세션은 독립적으로 detach/attach됩니다

윈도우 (Window)

윈도우는 세션 안에 있는 탭 개념입니다. 하나의 세션 안에 여러 윈도우를 만들어 각각 다른 작업을 할당할 수 있습니다. 터미널 하단 상태바에 탭처럼 표시됩니다.

페인 (Pane)

페인은 윈도우 안에서 화면을 분할한 각각의 영역입니다. 하나의 윈도우에서 좌우 또는 상하로 터미널을 나눠 동시에 여러 작업을 볼 수 있습니다. 예를 들어 왼쪽 페인에서 Claude Code를 실행하고 오른쪽 페인에서 개발 서버 로그를 모니터링하는 방식이 전형적인 사용 패턴입니다.

핵심 인사이트: 세션은 프로젝트, 윈도우는 역할(예: 에디터/서버/테스트), 페인은 동시 뷰로 구분하면 복잡한 개발 환경도 논리적으로 정리됩니다.

---

3. 필수 단축키 완전 정리

프리픽스(Prefix) 개념

tmux의 모든 단축키는 프리픽스(Prefix)를 먼저 입력한 뒤 명령키를 눌러야 작동합니다. 기본 프리픽스는 Ctrl+B입니다.

예를 들어 새 윈도우를 만들려면 Ctrl+B를 누른 뒤 손을 떼고 c를 누릅니다. 이 문서에서는 Prefix + 키 형태로 표기합니다.

세션 관련 단축키

동작	명령
tmux 새 세션 시작 (외부)	tmux 또는 tmux new
tmux 내부에서 새 세션 생성	Prefix → :new
세션 목록 보기	Prefix → s
세션 detach (분리)	Prefix → d
세션 재연결 (attach)	tmux attach 또는 tmux a
실행 중인 세션 목록 확인 (외부)	tmux ls
세션 이름 변경	Prefix → $

윈도우 관련 단축키

동작	명령
새 윈도우 생성	Prefix → c
이전 윈도우로 이동	Prefix → p
다음 윈도우로 이동	Prefix → n
번호로 윈도우 직접 이동	Prefix → 0~9
윈도우 목록 보기	Prefix → w
윈도우 이름 변경	Prefix → ,

페인 관련 단축키

동작	명령
수평 분할 (좌우)	Prefix → %
수직 분할 (상하)	Prefix → "
페인 이동 (방향키)	Prefix → ←↑↓→
페인 최대화 / 원복	Prefix → z

z(줌) 단축키 활용법: 페인을 여러 개 나눠 쓰다 보면 각 페인이 작아져서 내용이 잘 안 보일 때가 있습니다. 이때 해당 페인에서 Prefix → z를 누르면 전체 화면으로 확대되고, 다시 누르면 원래 레이아웃으로 돌아옵니다. 하루에도 수십 번 쓰게 되는 필수 단축키입니다.

윈도우 목록(w)을 활용한 빠른 이동

Prefix → w를 누르면 모든 세션의 윈도우가 펼쳐진 목록으로 표시됩니다. 이 목록에서:

1. 방향키로 이동 후 Enter를 눌러 진입하거나
2. 목록 좌측에 표시되는 인덱스 번호를 키보드로 바로 입력해 즉시 이동할 수 있습니다

s(세션 목록)보다 w(윈도우 목록)가 더 많은 정보를 한눈에 보여주기 때문에, 실무에서는 w를 주로 사용하는 것을 권장합니다.

---

4. tmux 설정 파일 최적화

tmux의 설정 파일은 홈 디렉터리의 ~/.tmux.conf에 위치합니다. 기본 설정만으로도 사용할 수 있지만, 아래 설정들을 추가하면 생산성이 크게 올라갑니다.

프리픽스 키 리매핑

기본 프리픽스인 Ctrl+B는 키보드에서 손 위치상 입력하기 불편합니다. Ctrl+Space로 리매핑하면 훨씬 자연스럽게 사용할 수 있습니다.

# ~/.tmux.conf

# 기존 Ctrl+B는 유지하고 Ctrl+Space도 프리픽스로 추가
set -g prefix2 C-Space
bind C-Space send-prefix

히스토리 리밋 확장 (필수)

# 기본값 2,000줄 → 50,000줄로 확장
set -g history-limit 50000

tmux는 각 페인에서 스크롤할 수 있는 출력 내용을 메모리에 보관합니다. 기본값은 2,000줄인데, 개발 서버를 오래 켜두면 로그가 금방 이 한계를 초과합니다. 50,000줄 이상으로 늘려두는 것을 강권합니다.

마우스 모드 활성화 (필수)

# 마우스로 페인 클릭 이동 및 크기 조절 허용
set -g mouse on

마우스 모드를 활성화하면:

• 마우스 클릭으로 페인을 선택할 수 있습니다
• 페인 경계선을 드래그해서 크기를 조절할 수 있습니다
• 단축키를 쓰기 어려운 상황에서 빠르게 조작할 수 있습니다

Vim 방향키(hjkl) 페인 이동

# Option(Alt)+hjkl로 페인 이동
bind -n M-h select-pane -L
bind -n M-j select-pane -D
bind -n M-k select-pane -U
bind -n M-l select-pane -R

Vim의 방향키 규칙(h=왼쪽, j=아래, k=위, l=오른쪽)을 tmux 페인 이동에 연결하면 키보드에서 손을 거의 움직이지 않고도 빠르게 페인을 전환할 수 있습니다. 이 설정은 tmux뿐 아니라 SSH로 원격 서버 접속 시에도 동일하게 활용할 수 있으므로, 처음에 생소하더라도 익혀두면 장기적으로 큰 이득입니다.

상태바 커스터마이징 예시

상태바(status bar) 우측에는 현재 Git 브랜치, CPU 사용률, 메모리, 배터리, 시간을 표시하도록 구성할 수 있습니다. 좌측에는 세션명과 활성 윈도우가 강조 표시되도록 설정하면 여러 세션을 운영할 때 현재 위치를 즉시 파악할 수 있습니다.

테마, 플러그인, 키 바인딩까지 포함한 설정 파일 전체를 그대로 적용하면 동일한 환경을 구성할 수 있습니다.

---

5. tmux 스크립트로 개발 환경 자동화하기

tmux의 진정한 강점은 프로그래매틱(programmatic) 제어입니다. 단순히 수작업으로 창을 나누는 것을 넘어, 쉘 스크립트로 전체 개발 환경을 코드로 정의하고 한 번의 명령으로 재현할 수 있습니다.

핵심 스크립트 명령어

send-keys: 다른 페인에 명령어 전송

# 문법: tmux send-keys -t [세션:윈도우.페인] "명령어" Enter

# 예시: 현재 세션 0번 윈도우 0번 페인에 'npm run dev' 전송
tmux send-keys -t 0:0.0 'npm run dev' Enter

# 예시: frontend 세션 1번 윈도우 1번 페인에 Claude Code 실행
tmux send-keys -t frontend:1.1 'claude' Enter

send-keys는 마치 사람이 키보드를 치는 것처럼 특정 페인에 명령어를 주입합니다. 이를 이용하면 스크립트 한 줄로 개발 서버 실행, 에이전트 구동 등 반복 작업을 자동화할 수 있습니다.

capture-pane: 특정 페인의 출력 내용 가져오기

# 문법: tmux capture-pane -t [세션:윈도우.페인] -p

# 예시: frontend 세션 0번 윈도우 0번 페인의 최근 출력 캡처
tmux capture-pane -t frontend:0.0 -p

capture-pane은 특정 페인의 현재 화면 내용(로그 등)을 텍스트로 읽어옵니다. 이것이 AI 에이전트가 다른 페인의 개발 서버 로그를 읽어오는 핵심 메커니즘입니다.

전체 개발 환경 자동화 스크립트 예시

여러 프로젝트를 동시에 작업할 때, 매번 수작업으로 세션·윈도우·페인을 구성하는 것은 번거롭습니다. 아래와 같은 구조의 스크립트를 만들어두면 한 번의 실행으로 전체 환경이 세팅됩니다.

#!/bin/bash
# dev-start.sh: 전체 개발 환경 한 번에 세팅

# --- 백엔드 세션 ---
tmux new-session -d -s backend -n 'api-server'
tmux send-keys -t backend:api-server 'npm run dev:backend' Enter
tmux split-window -h -t backend:api-server
tmux send-keys -t backend:api-server.1 'claude' Enter

# --- 프론트엔드 세션 ---
tmux new-session -d -s frontend -n 'dev-server'
tmux send-keys -t frontend:dev-server 'npm run dev:frontend' Enter
tmux split-window -h -t frontend:dev-server
tmux send-keys -t frontend:dev-server.1 'claude' Enter

# --- Claude 에이전트 세션 ---
tmux new-session -d -s claude
# 프로젝트별 Claude Code 페인 생성
for project in proj-a proj-b proj-c; do
  tmux new-window -t claude -n $project
  tmux send-keys -t claude:$project 'claude' Enter
done

# 완료 후 첫 세션에 attach
tmux attach -t backend

실제 현업에서 활용하면, 이 스크립트 한 줄로 세션 3개, 윈도우 13개를 동시에 구성할 수 있습니다. 매일 아침 개발 환경을 여는 시간이 수 분에서 수 초로 단축됩니다.

Claude Code에서 tmux 스크립트 활용하기

Claude Code 자체도 tmux의 capture-pane, send-keys를 직접 호출할 수 있습니다. 예를 들어 Claude Code에게 다음과 같이 요청할 수 있습니다:

"0번 페인에서 현재 개발 서버 로그를 확인해서 요약해줘"

Claude Code는 내부적으로 tmux capture-pane으로 해당 페인의 로그를 가져와 분석하고, 오류 내용을 요약해 줍니다. 현재 작업 중인 윈도우가 아니라도, 다른 세션의 다른 윈도우에 있는 페인 로그까지 가져올 수 있습니다.

---

6. 멀티 AI 에이전트 교차 검증(Cross Verification) 워크플로

제가 tmux를 가장 좋아하는 이유가 바로 이겁니다. 단일 에이전트로 개발을 이어가다 보면 컨텍스트 윈도우가 소진될수록 답변 품질이 떨어지는 문제가 생기죠. 이걸 해결하는 방법 중 하나가 여러 에이전트를 병렬로 스폰해 교차 검증하는 것입니다.

크로스 검증(Cross Verification) 스킬 개요

[Claude Code - 팀 리드]
    ├── [Codex CLI - 리뷰어 에이전트]  → Pane 1에서 실행
    └── [Gemini CLI - 리뷰어 에이전트] → Pane 2에서 실행

1. Claude Code(팀 리드)가 결과물을 생성합니다
2. send-keys로 Codex CLI 에이전트를 별도 페인에 스폰, 동일 결과물을 검증하게 합니다
3. 동시에 send-keys로 Gemini CLI 에이전트를 또 다른 페인에 스폰, 동일 조건으로 검증합니다
4. 두 에이전트의 검증 결과가 완료되면 capture-pane으로 각각의 출력을 수집합니다
5. Claude Code 팀 리드가 두 에이전트의 인사이트를 종합해 최종 결론을 냅니다
6. 팀 리드가 완료 후 스폰했던 에이전트 페인을 자동으로 정리합니다

왜 교차 검증이 효과적인가: 동일한 모델로 검증하면 편향된 결과가 나올 수 있습니다. Claude, Codex, Gemini는 각각 다른 학습 데이터와 추론 방식을 가지므로, 같은 문제에 대해 서로 다른 관점의 인사이트를 제공합니다. 이를 종합하면 단일 모델보다 훨씬 정확하고 풍부한 결론을 얻을 수 있습니다.

멀티스레드 개발 패러다임의 등장

과거에는 하나의 에이전트를 순차적으로 쓰는 단일 스레드 개발이 일반적이었습니다. 그런데 지금은 여러 에이전트를 병렬로 띄워놓고 관리하는 멀티스레드 개발이 빠르게 주류가 되고 있죠. 실제로 에이전트 하나만 쓰는 분보다 여러 개를 동시에 굴리는 분이 훨씬 많아진 것 같습니다.

구분	단일 스레드 개발	멀티스레드 개발
에이전트 수	1개	2개 이상
컨텍스트 관리	하나의 세션에 누적	역할별 분리로 각 세션 신선 유지
검증 방식	동일 에이전트 자체 검증	다른 모델로 교차 검증
tmux 활용도	낮음	높음 (필수 인프라)
생산성	상대적으로 낮음	상대적으로 높음

tmux는 이 멀티스레드 개발 패러다임을 터미널 레벨에서 완벽하게 지원하는 유일한 도구입니다. send-keys로 에이전트를 스폰하고, capture-pane으로 결과를 수집하고, 세션·윈도우·페인으로 에이전트를 격리 관리하는 모든 것이 tmux의 네이티브 기능입니다.

---

7. 추천 도구: yazi 파일 탐색기 연동

tmux와 함께 활용하면 좋은 터미널 기반 파일 탐색기로 yazi를 추천합니다. 터미널 밖으로 나가지 않고 파일 시스템을 탐색하고, 파일 내용을 빠르게 미리보기 할 수 있습니다.

설정 파일에 다음처럼 프리픽스 + Tab 키에 yazi를 바인딩하면, 현재 작업 중인 페인 옆에 파일 탐색 패널이 바로 열립니다:

# ~/.tmux.conf
# Prefix + Tab으로 yazi 파일 탐색기 토글
bind Tab split-window -h 'yazi'

Prefix → z로 줌인해 yazi 패널만 전체 화면으로 크게 볼 수 있고, 탐색이 끝나면 다시 z로 원래 레이아웃으로 복귀하면 됩니다.

---

마무리: tmux를 지금 시작해야 하는 이유

tmux는 학습 곡선이 있는 도구입니다. 처음에는 프리픽스 개념도 낯설고, 단축키도 많아 보이고, 설정 파일도 직접 손봐야 하죠. 하지만 한 번 익숙해지면 정말 다른 터미널 쓰기가 힘들어집니다.

제가 말하고 싶은 건, 지금은 그 진입 장벽을 넘어야 할 이유가 매우 명확하다는 겁니다. AI 에이전트를 두 개 이상 동시에 운용하는 분이라면, tmux 없이는 세션 관리, 병렬 실행, 크로스-페인 통신 중 어느 것도 효율적으로 하기 어렵습니다.

지금 당장 시작할 수 있는 3단계 로드맵:

1. 오늘: Ghostty(또는 현재 쓰는 터미널)에서 tmux를 실행하고 Ctrl+B + %, Ctrl+B + ", Ctrl+B + z만 익힙니다
2. 이번 주: ~/.tmux.conf에 히스토리 리밋 확장과 마우스 모드를 설정하고, 세션/윈도우 이름 붙이는 습관을 만듭니다
3. 다음 달: 자주 쓰는 개발 환경을 쉘 스크립트로 정의하고, Claude Code가 capture-pane으로 다른 페인의 로그를 읽어오는 워크플로를 구성해 봅니다

거의 19년 된 도구가 AI 에이전트 시대에 가장 빛을 발하고 있다는 게 역설적이면서도 재밌죠. 잘 설계된 도구는 시대를 초월한다고 봅니다. tmux가 바로 그런 도구입니다. 여러분도 꼭 한 번 활용해 보면서 생산성이 확 올라가는 걸 느껴 보면 좋겠습니다.

---

관련 영상

이 글과 연결된 영상은 개발동생 유튜브 채널에서 보기에서 확인할 수 있습니다.