한 번에 tmux를 IDE로,
덤으로 쓰기 좋은 작은 플러그인 열한 개
프로젝트를 열 때마다 저는 수동으로 서너 번 split합니다. 파일 트리 한 칸, 편집용 한 칸, git 한 칸, AI 한 칸입니다. 그러다 매번 나누는 게 귀찮아져서, 지난 반년 동안 tmux 설정에 쌓아 둔 맞춤 기능을 하나씩 독립적인 플러그인으로 떼어 내니 열두 개가 됐습니다. 이 글은 플러그인 이름을 하나씩 나열하기보다 불편했던 상황을 따라갑니다. 자기 상황과 맞닿는 부분만 읽으면 됩니다.
전부 설치할 필요는 없습니다. 모두 TPM을 쓰며, 설정은 이런 모양입니다.
다른 플러그인으로 바꿀 때는 @plugin 뒤의 문자열만 바꾸면 됩니다. 모두 github.com/operonlab 아래에 있고, 저장소 이름이 곧 플러그인 이름입니다. (그 페이지에는 tmux-webui도 나오는데, 이는 pane을 브라우저로 가져오는 서비스이지 TPM 플러그인이 아니므로 이 글에서는 다루지 않습니다.)
프로젝트를 열면 그 네 칸이 바로: tmux-workdesk
prefix + i를 누르면 1초 만에 IDE 레이아웃으로 배치됩니다커서가 어느 프로젝트 디렉터리에 있든 prefix + i를 누르면 화면이 1초 만에 IDE 레이아웃으로 바뀝니다. 왼쪽에는 yazi 파일 트리, 가운데는 글을 쓰는 칸, 아래에는 lazygit, 오른쪽에는 claude가 놓입니다. 다시 누르면 같은 window로 돌아가며 두 번째 창은 열지 않습니다. 각 칸에서 무엇을 실행할지, 너비를 얼마나 줄지도 바꿀 수 있습니다.@workdesk-main-cmd 'nvim' 처럼 한 줄이면 됩니다. 어느 칸을 빈 문자열로 설정하면 그 칸은 건너뜁니다.
prefix + g 는 또 다른 배치 방식으로, 현재 창을 2×2 격자로 만듭니다. 세로 열, 가로 행 같은 배치에도 직접 키를 지정할 수 있습니다. 이 배치들은 칸을 추가할 뿐 없애지 않아서, 전환해도 기존 칸들이 제자리에서 다시 배열됩니다.
기본 prefix + i 는 tmux에 내장된 창 정보 표시 키를 덮어씁니다. 신경 쓰인다면 @workdesk-ide-bind 로 바꾸면 됩니다.
창이 80×24에 갇힐 때: tmux-autosize
tmux-autosize는 연결, 크기 변경, 창 전환, 창 열기 때 갇힌 창을 클라이언트의 실제 너비와 높이에 맞춥니다. 상태 표시줄에 아무것도 놓지 않고 공간도 차지하지 않습니다. 하는 일은 이것뿐입니다.
그런데 어떤 window는 전체 크기가 80x24인 채로 남습니다. 그 안을 또 서너 칸으로 나누면 칸마다 스무 열 남짓이라 아무것도 읽을 수 없고, 어떻게 해도 커지지 않습니다. 대개 스크립트나 에이전트가 백그라운드에서 연 창이라 클라이언트가 한 번도 보지 못했고, 처음부터 tmux 기본 크기로 만들어진 것입니다.
저는 Dock을 왼쪽에 둔 27인치 2K 모니터에서 tmux를 씁니다. window 하나의 너비가 356열이고 네 칸으로 나눠도 칸마다 88열이 남습니다. 이게 정상일 때의 모습입니다.
역할을 솔직히 말하면, tmux 기본 window-size latest를 쓰는 경우에는 백그라운드 창이나 너무 이른 attach 같은 구석을 보완하는 안전장치에 불과합니다. window-size manual 로 바꿔야 주력 도구가 됩니다. 또 기록을 스크롤하는 동안에는 크기 변경을 미룹니다. 크기를 바꾸면 tmux가 스크롤백 전체를 다시 배치해야 해서 기록이 길수록 비용이 큽니다 (상위 프로젝트에도 비슷한 멈춤 사례가 있습니다).
한밤중에 mac mini가 멈추고 AI가 모두 기억을 잃었을 때: tmux-agent-resume
tmux-resurrect는 레이아웃은 되살려도 대화는 되살리지 못합니다. tmux-agent-resume는 바로 그 부분을 메웁니다. 저장 전에 각 pane에서 어떤 AI가 실행 중인지, 그 대화에 어떻게 다시 연결할지를 기록하고, 복원 후 연결 명령을 입력해 AI가 처음부터 시작하지 않고 중단 지점부터 이어 가게 합니다. 현재 여덟 개 CLI(Claude Code, Codex, Antigravity, Copilot, OpenCode, Kimi, Hermes, Qwen)를 알아봅니다. 서비스마다 대화 ID를 숨겨 놓은 곳이 다릅니다.
이 기능을 만든 계기는 몹시 난감했던 어느 밤입니다. 서재에서 늘 켜 두는 mac mini가 한밤중에 멈췄고, 백그라운드 감시 프로그램이 설계대로 터미널을 강제로 재시작했습니다. 레이아웃은 tmux-resurrect 로 되살렸지만, 그 안의 AI 도우미들은 모두 기억을 잃어 어디까지 이야기했는지 잊었습니다. 돌아온 칸은 비어 있거나 CLI가 완전히 새 빈 session으로 다시 열렸습니다.
솔직히 말해야겠습니다. tmux-agent-resume는 실제로 여러분의 pane에 명령을 입력하고 Enter를 누릅니다. 그래서 모든 명령을 먼저 허용 목록에 대조하고, 형식이 맞지 않으면 버립니다. 빈 프롬프트에 멈춰 있는 칸에만 동작합니다. 어떤 명령을 입력할지 먼저 보고 싶다면 @agent-resume-dry-run 1를 켜면 됩니다. 대신 여덟 개 타사 도구의 인터페이스에 묶입니다. 그쪽이 바뀌면 저도 고쳐야 합니다. 현재는 macOS만 지원합니다.
나머지는 상황별로 빠르게 살펴보겠습니다
앞서 본 workdesk, autosize, agent-resume 세 가지가 제게 가장 크게 와닿았습니다. 나머지 아홉 개는 각각 구체적인 불편 하나를 풉니다. 오른쪽 클릭 메뉴, 떠 있는 터미널, 중첩 tmux의 키 충돌, 상태 표시줄의 숫자 같은 것들입니다.
마우스는 익숙하지만 단축키는 외우기 어렵다면
tmux-context-menu는 분할, 확대, 닫기, 이름 바꾸기를 마우스 오른쪽 클릭 메뉴로 옮깁니다. 메뉴는 클릭한 자리에 뜹니다. (마우스를 쓰고 싶지 않다면 Alt+q를 누르면 됩니다.) 선배 격인 jaclu/tmux-menus 와는 방향이 다릅니다. 그쪽은 키보드로 단계를 따라가는 메뉴 트리이고, 이쪽은 ‘클릭한 자리에 메뉴가 뜬다’는 데만 집중하도록 일부러 범위를 좁혔습니다.
필요할 때 꺼내 쓰는 임시 터미널을 원한다면
tmux-floatpane은 prefix + t 를 누르면 화면 중앙에 작은 터미널을 띄우고, 다시 누르면 접습니다. 안에 남겨 둔 내용은 다음에 열어도 그대로 있습니다. 이 플러그인은 omerxx/tmux-floax 의 개선된 포크입니다. 원래 설계와 구현은 Omer Hamerman의 공입니다. 저는 쓰다가 마주친 자잘한 문제 몇 가지를 말끔히 고치고 싶었을 뿐입니다. GPL-3.0 저작물을 수정했으므로 이 포크도 GPL-3.0입니다.
자주 ssh로 원격에 접속해 그 안에서 tmux를 또 연다면
tmux 두 겹이 Ctrl-b를 서로 가로챕니다. tmux-passthrough는 ‘잠깐 비켜 줘’ 키(기본 F12)를 제공합니다. 한 번 누르면 바깥쪽이 조용해지고 모든 키가 안쪽으로 전달됩니다. 상태 표시줄은 따뜻한 복숭아색으로 바뀌어 지금 어느 층에 있는지 알려 줍니다. 선배 격인 tmux-suspend 보다 안전장치가 하나 더 있습니다. F12는 이 칸이 실제로 원격 연결일 때만 동작하며, 로컬에서 잘못 눌러도 아무 일도 일어나지 않습니다.
시스템 수치를 상태 표시줄에 놓고 싶다면
tmux-sysmon은 CPU, 메모리, 디스크, 네트워크 속도에 대한 네 가지 #{...} 자리표시자를 제공합니다. 순수 텍스트만 출력하므로 테마는 직접 적용하면 됩니다. (macOS에서는 디스크 경로를 /System/Volumes/Data 로 지정해야 정확히 측정됩니다.) 이런 환경 정보를 넣을 줄을 통째로 하나 더 원한다면 tmux-pillbar가 첫 줄 아래에 상태 표시줄을 추가하고 왼쪽, 가운데, 오른쪽 세 칸으로 나눠 줍니다. 테마가 아닌 틀이므로 색과 내용은 직접 채워야 합니다.
먼저 ‘터미널에서 여러 AI CLI를 동시에 실행하는’ 사람을 위한 두 가지입니다. 그렇지 않다면 건너뛰세요. tmux-agent-status는 상태 표시줄에 AI 몇 개가 작업 중인지, 여러분의 승인을 기다리는지, 쉬고 있는지 표시합니다. 실행 중인 AI가 하나도 없으면 캡슐도 사라집니다. tmux-llm-usage는 직접 연결한 사용량과 할당량을 렌더링합니다. 수치를 대신 가져오지는 않고, JSON 규약과 버벅거리지 않는 캡슐 하나만 제공합니다.
이 두 캡슐과 앞서 본 agent-resume는 제가 만들 당시 참고할 대상이 가장 없었던 세 가지입니다. 앞의 플러그인들은 누구의 아이디어를 바탕으로 했는지 말할 수 있지만, 이 세 가지는 당시 기성품을 찾지 못해 직접 만들었습니다. 나중에야 같은 영역을 다루는 이들이 있다는 걸 알았습니다. tmuxwatch는 관찰만 하는 TUI를, harness-terminal은 ‘에이전트가 여러분을 기다리는 중’을 감지하는 네이티브 터미널을 만듭니다. 접근 방식은 저와 다르지만 같은 문제들을 풉니다.제가 못 찾았다고 해서 없는 건 아닙니다. 당시 제 눈에 띄지 않았을 뿐입니다.
유지 비용도 이 세 가지가 가장 큽니다. 여덟 개 타사 AI 도구의 인터페이스를 계속 따라가야 하고, 그쪽이 바뀌면 저도 고쳐야 합니다.
하나는 과거를, 하나는 현재를: tmux-agent-history / tmux-agent-dock
상태 표시줄의 agent-status와 llm-usage는 ‘몇 개가 작업 중이고 몇 개가 멈춰 있는지’만 알려 줍니다. 여기서는 그다음 질문, ‘그래서 어느 에이전트로 가야 하지?’에 답합니다. 둘 다 상태 표시줄에 들어가지 않고, 키 하나로 전체 높이의 목록을 엽니다. 하나는 지난 대화를 뒤지고, 다른 하나는 지금 실행 중인 에이전트를 지켜봅니다.
CLI마다 대화를 하드디스크에 저장하는 위치와 형식이 다릅니다. Claude Code는 한 종류의 JSONL로 쓰고, Codex는 또 다른 방식이며, Gemini는 다른 폴더에 넣습니다. tmux-agent-history는 아홉 가지(Claude Code, Codex, Gemini, Copilot, OpenCode, Kimi, Hermes, agy, Qwen)를 목록 하나로 모읍니다. 행을 선택하면 옆에서 해당 대화를 미리 보여 줍니다. 지난주에 끝내지 못한 논의를 찾으려고 CLI를 하나씩 열 필요가 없습니다. 파일을 읽기만 하고 실행 중인 에이전트는 건드리지 않습니다.
⏎ 로 이동합니다tmux-agent-dock은 현재 창 오른쪽에 사이드바를 열어 이 server에서 실행 중인 모든 에이전트를 실시간으로 나열합니다. 여러분의 승인을 기다리는 에이전트가 앞에 옵니다. 커서를 옮길 때마다 위쪽에는 해당 에이전트의 화면이 나타납니다.⏎ 로 이동하거나⌃x 로 종료할 수 있습니다. 상태 판별에는 agent-status 캡슐과 같은 방식을 쓰므로 별도의 백그라운드 프로그램을 실행하지 않고 아무것도 저장하지 않습니다.
이 두 가지에도 앞서 본 agent-status, llm-usage, agent-resume와 같은 부담이 있습니다. 각 CLI가 기록을 어떻게 저장하고 화면은 어떤 모습인지 알아야 하므로 지원 대상을 하나 늘릴 때마다 규칙도 보태야 합니다. 현재는 macOS에서만 검증했습니다.
플러그인 열두 개 기능 비교
| 플러그인 | 한 줄 설명 | 최소 tmux | 라이선스 |
|---|---|---|---|
| tmux-workdesk | 한 번에 현재 프로젝트를 IDE 레이아웃으로 배치하고, 격자와 세로 열 등 기하학적 배치도 제공 | 2.4 | MIT |
| tmux-autosize | 백그라운드에서 80×24 등에 갇힌 창을 올바른 크기로 조정 | 3.0 | MIT |
| tmux-context-menu | tmux에서 오른쪽 클릭으로 마우스 옆에 동작 메뉴 표시 | 3.3a | MIT |
| tmux-floatpane | 필요할 때 바로 여는 떠 있는 scratch 터미널, 내용 유지 | 3.3 | GPL-3.0 |
| tmux-passthrough | 한 번에 제어권을 원격 쪽 tmux에 넘겨 키 충돌 방지 | 2.4 | MIT |
| tmux-sysmon | 상태 표시줄에 CPU/메모리/디스크/네트워크 속도 네 가지 수치 표시 | 1.8 | MIT |
| tmux-pillbar | 상태 표시줄 한 줄을 더 열고 왼쪽, 가운데, 오른쪽 세 칸을 원하는 내용으로 채우기 | 2.9 | MIT |
| tmux-agent-status | 상태 표시줄에 작업 중/멈춤/대기 중인 AI 수 표시 | 2.1 | MIT |
| tmux-llm-usage | 상태 표시줄에 직접 연결한 AI 사용량/할당량 표시 | 1.8 | MIT |
| tmux-agent-resume | 재시작 후 각 pane의 AI 대화를 중단 지점부터 이어 주기(tmux-resurrect 필요) | 1.9 | MIT |
| tmux-agent-history | 하드디스크에 저장된 여러 AI CLI의 지난 대화를 목록 하나에서 찾아 선택하면 미리 보기 | 1.9 | MIT |
| tmux-agent-dock | 오른쪽 사이드바에 실행 중인 에이전트를 실시간으로 표시, ⏎로 이동하고 ⌃x로 종료 | 1.9 | MIT |
고르기 귀찮다면: 매일 프로젝트를 열거나 여러 칸을 한눈에 보고 싶을 때는 workdesk (prefix + i 는 IDE 배치,prefix + g 는 격자 배치)입니다. 크기가 자꾸 잘못되면 autosize를 쓰고, AI를 여러 개 실행한다면 마지막 다섯 가지를 보세요. 하나만 설치하고 습관도 바꾸고 싶지 않다면 autosize가 가장 부담이 적습니다.
.tmux.conf를 붙여 넣고 무엇을 설치할 수 있는지 확인하기
위 표에는 최소 버전이 열두 개나 있어 하나씩 확인하기 번거롭습니다.먼저 tmux -V 가 출력한 줄과 자신의 ~/.tmux.conf 를 여기에 붙여 넣으면 같은 표를 기준으로 버전 조건을 확인하고, 이 글에 나온 다섯 키 (prefix + i,prefix + g,prefix + t,Alt+q,F12)가 기존 키 바인딩과 충돌하는지도 검사한 다음, conf에 바로 붙여 넣을 수 있는 TPM 블록을 만듭니다. 모든 처리는 브라우저 안에서 이루어지며 붙여 넣은 내용은 어디에도 전송되지 않습니다. conf에 token, 비밀번호, 남에게 보여 주고 싶지 않은 경로가 있다면 먼저 지우고 붙여 넣으세요.
상수의 출처는 모두 이 글에 있습니다. 열두 플러그인의 최소 tmux 버전과 라이선스는 ‘플러그인 열두 개 기능 비교’ 표에서 그대로 옮겼고, 검사할 다섯 키는 ‘이 부분을 가져가세요’의 prompt 2번 항목에 제가 직접 적었습니다.@workdesk-ide-bind와 TPM 블록을 run 줄 위에 놓을 것, 저장 후 prefix + I를 누를 것도 모두 이 글의 원문 그대로입니다. 플랫폼 제한은 이 글에서 세 가지만 밝힙니다. agent-resume와 agent-dock은 ‘macOS만 지원’, agent-history는 ‘macOS에서만 검증’이라고 썼습니다. 나머지 아홉 가지가 Linux/WSL에서 어떻게 동작하는지는 언급하지 않았습니다.이 도구가 읽는 것은 붙여 넣은 문자열이지 여러분의 컴퓨터가 아닙니다—직접 tmux -V를 실행하지 않았고, TPM이 설치됐는지도 확인하지 않으며, source-file 를 따라 다른 파일을 읽지도 않습니다. 따라서 ‘검출되지 않음’은 다른 파일에서 충돌이 일어났다는 뜻일 수도 있습니다. 이미 설치한 다른 플러그인이 키 바인딩을 만들었을 수도 있지만, 그 줄이 conf에 없으면 여기서는 볼 수 없습니다. 충돌이 나도 이 글에서 알려 줄 수 있는 키 변경 옵션 이름은 workdesk의 것뿐입니다. floatpane, passthrough, context-menu의 변경 방법은 각 repo에서 찾아야 합니다. 위의 ‘이 부분을 가져가세요’ prompt는 에이전트가 여러분의 컴퓨터에서 실제로 tmux -V를 실행하고 conf도 직접 읽게 하므로 여기보다 정확합니다. 이 도구의 쓸모는 에이전트가 곁에 없을 때 즉시 답을 얻고, 어느 줄에서 충돌하는지 확인하는 데 있습니다.
이 부분을 가져가세요
우선 설정 파일에서 해결하고, 같은 일이 세 번째로 귀찮아질 때 플러그인으로 떼어 낼 만합니다—이 열두 가지 중 어느 것도 먼저 플러그인을 만들기로 정하고 시작한 게 아닙니다. 대부분은 설정 파일의 몇 줄이 너무 거슬려서 떼어 냈고, 몇 가지는 그날 한밤중 재시작처럼 실제 사고 때문에 만들었습니다. 반대로 딱 한 번 불편했던 일은 설정 파일에 적어 두면 충분합니다.
어느 것이 자신에게 쓸모 있는지 모르겠다면 아래 문구를 AI에 붙여 넣고 실제 환경에 맞춰 판단하게 하세요.
더 읽을거리
여섯 링크 중 셋은 제가 올라선 선배들의 어깨입니다(tmux-floax, tmux-suspend, tmux-menus). 나머지는 tmux-resurrect와 제가 겪은 issue, 비슷한 기능을 앞서 만든 사례입니다.
| 자료 | 왜 중요한가 |
|---|---|
| omerxx/tmux-floax | tmux-floatpane의 상위 프로젝트입니다. 떠 있는 scratch 터미널의 원래 설계는 여기서 나왔고, 제 포크는 쓰면서 겪은 몇 가지 문제를 말끔히 고쳤을 뿐입니다. |
| MunifTanjim/tmux-suspend | ‘prefix 전체를 다른 층에 넘긴다’는 길을 열어 줬습니다. 덕분에 passthrough에는 ‘원격 pane에서만 동작한다’는 안전장치가 필요하다는 걸 알았습니다. |
| jaclu/tmux-menus | context-menu의 범위를 좁혀야 한다는 생각을 정리하게 해 줬습니다. 그쪽은 키보드 메뉴 트리를 쓰고, 저는 마우스로 오른쪽 클릭한 자리를 씁니다. 두 방식은 서로 다른 습관을 위한 것입니다. |
| tmux-resurrect | 레이아웃을 되살리는 기존 도구입니다. 레이아웃만 되살리고 대화는 못 살리기 때문에 agent-resume 계층이 필요해졌습니다. 저장과 복원 기능에 바로 연결합니다. |
| tmux/tmux#4814 | ‘크기 변경으로 스크롤백 전체를 다시 배치하는’ tmux 상위 프로젝트의 멈춤 사례입니다. autosize의 ‘스크롤 중에는 크기 변경을 미룬다’는 동작은 같은 비용을 조심스럽게 피하는 방법입니다. |
| tmux-plugins/tmux-cpu | ‘status 안의 자리표시자 token을 다시 쓴다’는 방법을 agent-status와 sysmon 모두 따릅니다. sysmon이 같은 분야의 선배라고 솔직히 인정하는 도구이기도 합니다. |