tmux 로드맵 — 세션 관리를 익혀 작업 환경을 자동화하는 순서

tmux는 한 번 손에 익으면 터미널 작업 방식 자체가 바뀐다. 한국어 자료는 “세션·윈도우·패널 단축키”에서 끝나는 경우가 대부분인데, 매일 쓰는 사람은 그 너머로 들어간다. 이 로드맵은 그 흐름을 학습 줄기로 세운다 — 구조·cheatsheet(입문)에서 시작해 기본값을 다듬고(1단계), 플러그인으로 확장하고(2단계), 세션 부트스트랩으로 자동화(3단계)하는 데까지 한 줄기로 묶었다. 본인 위치에서 가까운 단계부터 진입하면 된다.

학습 흐름과 결이 다른 축 — 특정 환경에서만 막히는 클립보드 연동·자동 attach 트러블슈팅 — 은 아래 부록으로 분리했다. 실력을 쌓는 순서와 별개로, 같은 증상을 만났을 때 직행하면 된다.

한눈에 보기

구역	무엇을 다루나	성격
입문	세션·윈도우·패널 3계층 구조·설치·기본 단축키·타겟 문법	학습 전제
1단계	매일 체감되는 옵션으로 기본값 다듬기	줄기
2단계	플러그인(TPM) — 쓰기 → 만들기 → AI 에이전트 관제 응용	쓰기=줄기 · 만들기·응용=선택
3단계	세션 매니저(선언형)로 부트스트랩 자동화, 셸로 원리 해부	줄기 · 선택
부록	클립보드·자동 attach 트러블슈팅	다른 축

입문 — 구조와 cheatsheet

tmux를 처음 만지거나, 단축키가 자꾸 헷갈리는 단계.

글	핵심
tmux 정리본 (Cheat Sheet + 사용 가이드)	세션·윈도우·패널 3계층 구조, 설치, ~/.tmux.conf 기본, 자주 쓰는 단축키·복사 모드·스크롤 한 장

📎 치트시트 · tmux — 세션·윈도우·패널·복사 모드 단축키 빠른 참조 (GitHub)

여기까지만 알아도 “터미널이 닫혀도 살아있는 세션”은 누릴 수 있다.

join-pane·swap-pane에서 “뭐가 어디로 가는지” 헷갈린다면, 위 정리본 글의 “윈도우 합치기/분리” 절에 -s/-t와 session:window.pane 타겟 문법을 정리해 뒀다. 그런데 왜 merge-pane은 없고 옮기고·떼고·맞바꾸는 동사만 있는지 — pane이 프로세스라서 그렇다는 정신 모델은 tmux엔 왜 pane 병합이 없을까에서 다룬다.

다만 기본값은 손이 불편한 부분이 많아, 다음 단계에서 다듬는다.

1단계 — 설정 다듬기

기본값으로 한 달쯤 쓰면 어떤 옵션을 바꾸고 싶은지 감이 온다. 그 시점에 읽는 글.

글	핵심
tmux 유용한 설정 정리 (.tmux.conf 기준)	매일 체감되는 옵션만 추림 — ESC 지연 제거·True Color·마우스·분할 시 경로 유지·vi 복사모드·세션 트리 정렬

💡 완성형 배포판이라는 갈림길. 기본값을 손수 다듬는 대신, 잘 짜인 .tmux.conf를 통째로 상속하는 길도 있다 — Oh My Tmux!(25k⭐, 이 카테고리 독주). 무엇을 바꾸고 어떻게 커스텀하는지는 전용 글에서, 채택 판단은 2단계 beyond-essentials의 ‘다른 축’ 절에서 다룬다. 이 로드맵은 직접 조립을 택하지만, 반대 노선을 알고 고르는 편이 낫다.

2단계 — 플러그인으로 확장

tmux 자체로는 안 되는 영역(세션 저장·복원, 테마, Vim 패널 통합 등)이 플러그인으로 해결된다. TPM(Tmux Plugin Manager)이 사실상 표준. 이 단계는 쓰기 → 만들기 → 응용 세 갈래를 한 흐름으로 묶었다 — 남의 플러그인을 쓰다 보면 원리가 궁금해지고, 원리를 알면 필요한 걸 직접 만들게 되는 자연스러운 순서다. 뒤 두 갈래는 심화·선택이라, 쓰기만으로 충분하면 3단계로 건너뛰어도 된다.

쓰기 — 남의 플러그인 설치·설정

글	핵심
tmux 설정 & 플러그인 설명	TPM 설치·키바인딩, 대표 플러그인(tmux-sensible·tmux-resurrect·tmux-continuum·vim-tmux-navigator)을 .tmux.conf 예시와 함께
필수 그다음 — 요즘 얹는 tmux 플러그인	위 필수 6종 위에 얹는 층. catppuccin으로 상태바 현대화(방치된 themepack 대체)·tmux-yank·extrakto 추출·퍼지 계열을 별 개수·정착도 실측과 함께

만들기 — 직접 플러그인 제작 (심화)

플러그인을 쓰다 보면 “이건 왜 이렇게 동작하지”가 궁금해지는 순간이 온다. 그때 읽으면 tmux 플러그인 생태계 전체가 한 번에 풀린다.

글	핵심
tmux 플러그인은 어떻게 만드나 — CLI가 곧 API	런타임·SDK 없이 .tmux 셸 스크립트가 tmux CLI를 대신 호출하는 게 전부. 진입 스크립트 구조·설정형/상호작용형·set-hook·배포까지

응용 — AI 에이전트 여러 개 관제 (심화)

Claude Code·Codex 같은 AI 코딩 에이전트를 여러 개 동시에 굴리기 시작하면, 각 패널이 일하는 중인지·답을 기다리는지·끝났는지를 자동으로 감지하고 싶어진다. 앞의 훅·플러그인 지식을 그대로 얹는 실전 응용이라 여기 이어 붙였다.

글	핵심
tmux로 AI 에이전트 여러 개 관제하기 — herdr 대신 훅 기반 플러그인	전용 멀티플렉서(herdr)와 훅 기반 tmux 플러그인 비교. running/needs-input/done을 정확히 감지 — 대시보드가 목적이면 sidebar, 인라인이면 indicator. tmux 단축키는 하나도 안 건드리고
tmux 선택을 AI 에이전트 패널로 보내기 — Y 바인딩과 marked pane	셸 출력을 에이전트에 복붙하는 마찰을 copy-mode 바인딩 하나로. copy-mode가 nvim은 못 긁는 이유(alternate screen)와 {marked} 타깃 해소까지

3단계 — 세션 부트스트랩 자동화

같은 작업 환경을 매번 손으로 세팅하지 않으려면, 세션·윈도우·패널을 한 번에 만드는 부트스트랩이 답이다. 이건 이미 해결된 문제라 선언형 세션 매니저(smug·tmuxinator·tmuxp)가 정석 — YAML로 레이아웃만 적으면 띄워 준다. 직접 셸로 짜는 건 재발명이지만, 그 도구가 안에서 부르는 tmux 명령을 셸로 해부하면 원리가 잡힌다. (세션 매니저는 2단계 TPM 플러그인과 달리 tmux 밖의 외부 CLI다.)

글	핵심
tmux 세션 부트스트랩 — 세션 매니저와 그 속살(셸)	정석은 세션 매니저(smug/tmuxp/tmuxinator, 조건부 순위) — YAML 선언·이미 있으면 attach. 그 도구가 부르는 tmux 명령을 셸로 해부해 원리까지
smug — 의존성 없는 미니멀 tmux 세션 매니저 (선택)	세션 매니저 중 무의존·미니멀(Go 단일 바이너리)을 골랐다면 실전 — 기본 config·프리셋에 없는 커스텀 레이아웃을 layout 문자열로 고정·smug의 범위(freeze는 tmuxp)
sesh — 즉석 tmux 세션 전환 (피커) (선택 · 다른 축)	레이아웃을 선언하는 부트스트래퍼와 다른 범주 — fzf·zoxide로 디렉토리·git repo에서 세션을 즉석 전환. prefix+T 피커·핵심 CLI·부트스트래퍼에서 옮긴 이유

---

부록 — 상황별 트러블슈팅 (다른 축)

여기서부터는 “실력을 쌓는 순서”가 아니라, macOS·리눅스·서버를 오가며 tmux를 쓰다 특정 상황에서만 부딪히는 트러블슈팅 축이다. 겪고 있는 증상에 맞는 글로 곧장 들어가면 된다.

글	핵심
tmux 시스템 클립보드 — OSC52 / pbcopy / 한글	set-clipboard on 한 줄이 사실상 정답. pbcopy 경로의 LANG 함정과 tmux server 환경 캡처 메커니즘까지
tmux — 터미널 열 때마다 새 세션이 생기는 이유 (attach -t 함정)	attach -t default 하드코딩 + 정렬용 이름 접두어(0-default) 불일치로 매번 new로 빠지는 문제. 타깃 없는 tmux attach 한 줄로 해결

---

본인 위치에 따라:

• tmux를 처음 만진다면 입문 → 1단계만으로 충분하다.
• TPM·플러그인까지 가고 싶다면 2단계 — 쓰기로 시작해, 궁금해지면 직접 만들기·AI 관제 응용까지 한 흐름으로 이어진다.
• 여러 프로젝트를 매일 오가며 작업한다면 3단계 세션 매니저(부트스트랩)가 시간 절약이 큰 영역.
• 서버나 macOS에서 복사·붙여넣기가 깨진다면 클립보드 트러블슈팅 글로 직행.
• 터미널을 열 때마다 빈 세션이 새로 생긴다면 자동 attach 트러블슈팅 글로.
• AI 코딩 에이전트를 여러 개 굴린다면 2단계 ‘응용’의 에이전트 관제 글로.

단축키만 외우려고 시작했다가 결국 부트스트랩 스크립트까지 가는 게 자연스러운 흐름이다. Neovim과의 통합(vim-tmux-navigator 류)은 Neovim 로드맵 쪽도 함께 보면 좋다. 3단계에서 세션 매니저의 속살로 해부하는 셸 스크립트나 부록의 셸 시작 시 자동 attach는 결국 셸 자체를 다뤄야 하는 영역이라, 셸 로드맵과 함께 보면 앞뒤가 맞는다.