pytmux — 마우스로 쓰는 tmux, Claude Code 통합 터미널 멀티플렉서

Changelog

최근 수정사항

2026년 6월 2일 첫 커밋부터의 변경을 날짜별로 정리합니다. 아래는 가장 최신 날짜의 변경입니다.

🛠 최근 수정사항 · 2026-07-30 목요일 전체 변경 내역 →

안정 넓은 텍스트를 붙여넣으면 pytmux 가 몇십 초 동안 멈추던 것을 고쳤습니다. 테두리 문자를 걷어내는 검사가 줄 길이의 제곱으로 느려졌습니다 — 공백 10만 자 한 줄 32초 → 0.0035초. 마우스 복사도 함께 빨라졌습니다.
복사 Claude Code 의 ! … 명령을 긁어 복사하면 줄바꿈·들여쓰기가 섞여 그대로 붙여넣을 수 없던 것을 고쳤습니다. 앱이 스스로 접은 자리를 알아보고 펴서 클립보드에 넣습니다 — 로그·코드 줄은 건드리지 않습니다(set copy-unwrap off 로 끔).
마우스 안에서 돌던 앱이 갑자기 죽은 패널에서 마우스를 움직이면 프롬프트에 35;61;31M… 같은 글자가 박히던 것을 고쳤습니다. 앱이 되돌릴 틈 없이 죽어 켜진 채 남은 "마우스 좌표 요청" 을 pytmux 가 스스로 걷어냅니다 — 휠 스크롤백도 함께 돌아옵니다.
설정 설정 화면의 exit-empty 줄이 켜짐/꺼짐 대신 미상 으로만 보이던 것을 고쳤습니다. 서버가 보내 주는 현재값 묶음에 이 항목만 빠져 있었습니다 — 이제 실제 값이 그대로 보입니다.
Claude /model 로 모델을 바꿔도 상태줄 모델 배지가 한동안 옛 모델을 보이던 것을 고쳤습니다. 배지는 같은 이름을 세 프레임 연속 본 뒤 바꾸는데, 화면이 멈춰 있으면 다시 읽지 않아 세다가 얼었습니다 — 이제 바꾼 직후 곧바로 따라옵니다.
문서 소개 사이트를 최신 배포본에 맞춰 최신화했습니다. 상세 가이드 11장(원격 페더레이션)에 다중홉을, 6장(마우스로 제어)에 남은 마우스 요청 자동 회수를 실었습니다.

전체 변경 내역 →

Why pytmux

tmux 의 힘, 더 낮은 진입장벽

명령어를 다 외우지 못해도, 마우스를 더 쓰고 싶어도 괜찮습니다. 세 가지 방식 모두로 제어합니다.

🖱️

마우스 1급 지원

경계선 드래그로 패널 크기 조절, 클릭으로 포커스, 우클릭으로 메뉴, 휠로 스크롤백. 좌드래그로 복사, 패널 헤더를 끌어 두 패널을 맞바꿉니다.

🧭

메뉴 · 명령 프롬프트

단축키를 외우지 않아도 메뉴(prefix Enter)와 명령 프롬프트(prefix :)로 거의 모든 동작을 합니다.

♻️

셸 영속

셸 PTY 를 백그라운드 데몬이 보유합니다. 앱을 닫거나 터미널 창을 닫아도 셸은 계속 돌고, 다시 실행하면 그대로 이어 붙습니다.

🪟

윈도우 네이티브

tmux 와 달리 WSL·Cygwin 없이 윈도우에서 그대로 동작합니다. ConPTY 기반 pty-host 로 PowerShell·cmd 를 띄우고, macOS·Linux 와 같은 경험을 줍니다.

Core features

패널 · 탭 · 스크롤백, 익숙하게

탭 → 윈도우 → 패널 계층. 최상위는 탭이고, 각 탭을 패널 집합으로 분할합니다.

패널 분할과 활성 테두리

한 화면을 좌우·상하로 자유롭게 분할하고 중첩합니다. 패널이 둘 이상이면 각 패널을 테두리로 감싸고, 활성 패널은 파란색으로 강조합니다.

prefix % 좌우 분할 · prefix " 상하 분할
prefix z 로 패널 줌(전체화면) 토글
경계선을 마우스로 끌어 크기 조절, 패널 헤더를 끌어 swap

03 · 중첩 분할 레이아웃

상단 탭바와 여러 윈도우

탭이 하나여도 상단에 탭 인터페이스가 나타나고, 마지막 탭 오른쪽의 [+] 로 새 탭을 엽니다. 탭은 1번부터 번호가 매겨지고 드래그로 재정렬합니다.

활성 탭은 아래 콘텐츠와 연결된 노트북 탭 모양
탭 고정(pin), 이름 변경, 닫기 확인
하단 상태표시줄에 탭 목록 · 줌 상태 · 시계

08 · 다중 탭 + 상단 탭바

메뉴와 명령 프롬프트

우클릭 또는 prefix Enter 로 패널·레이아웃·탭 그룹으로 정리된 메뉴를 엽니다. prefix : 명령 프롬프트는 공백 검색·자동완성·인자 이력을 지원합니다.

서브메뉴로 정리된 계층형 메뉴
명령 팝업에서 전체 명령 목록 탐색
bind-key 로 런타임 키 재바인딩

36 · 서브메뉴 · 06 명령 프롬프트

패널별 스크롤백

copy-mode 로 따로 들어가지 않아도, 패널 위에서 휠을 올리면 바로 지난 출력을 봅니다. 패널마다 독립적입니다.

마우스 휠로 즉시 스크롤백 진입
스크롤백 텍스트 검색 · 점프
붙여넣기는 bracketed paste 로 한 번에(줄마다 실행 안 됨)

15 · 패널별 스크롤백

Claude Code 통합

토큰을 보고, 자동으로 잇습니다

패널에서 돌리는 Claude Code 의 상태·토큰·한도를 상태줄과 팝업으로 한눈에.

상태 표시 + 토큰 리밋 자동 재개

실행 중인 탭에 상태 아이콘(대기 ○ / 처리중 ◐ / 리밋 멈춤 ⊘)을 표시하고, 비활성 탭 작업이 끝나면 탭 배경색으로 알립니다. 사용량 리밋에 걸려 멈추면 해제 시각을 읽어 그때 자동으로 재개합니다.

prefix R 자동 재개 토글(상태줄 AR)
권한모드 footer 클릭 → auto / accept / default / plan 선택
claude-rules 로 시작 규칙 자동 주입
진행을 막는 화면(/rc 관리 메뉴 · 조직 관리설정 승인)은 기본 선택 그대로 자동 통과

12 · 토큰 리밋 자동 재개

토큰 사용량 팝업

상태줄의 토큰 배지를 클릭하면 기간 / 세션 / 한도 / 경고 노트북 탭과 [/usage] · [시나리오] 버튼으로 보는 사용량 팝업이 열립니다. 화면 스크랩이 아닌 ~/.claude/*.jsonl 트랜스크립트 회계로 cache_read 까지 정확히 집계합니다.

기간 뷰 — 월 → 주 → 일 → 시각 계층 트리로 시간 흐름을
세션 뷰 — Claude 세션별 합(탭:패널·타임스탬프)
한도 뷰 — /usage 실측 막대 + 리셋 카운트다운 시계 + 모델/컨텍스트 변경
머신 뷰 — 여러 컴퓨터의 사용량을 합쳤을 때만 붙는 탭(어느 컴퓨터가 얼마를 썼는지)

기간 · 세션 · 한도 탭

실제 Claude 패널에서

진짜 claude CLI 를 패널에서 돌리며 모델 배지, 프롬프트 이력 미리보기·점프, 작성창으로 쓴 긴 프롬프트 투입까지 그대로 동작합니다.

멀티라인 프롬프트 붙여넣기 · 이미지 붙여넣기 패스스루
프롬프트 히스토리 플러그인으로 보낸 프롬프트 점프
피드백 문구 자동 숨김 옵션
CJK 모호폭 자동 감지(:set ambiguous-width auto)와 화면 깨짐 자동 완화(claude-auto-redraw)로 글자 겹침 방지

22 · 실 Claude 패널

Operations

죽이지 않고 고치고, 멀리까지 잇습니다

실행 중인 셸을 살린 채 코드를 교체하고, ssh 너머의 다른 pytmux 서버에 붙습니다.

작업 보존 서버 재시작

restart-server · restart-all · restart-check(드라이런)로, 열린 패널의 셸 · 실행 중 프로그램 · 스크롤백을 살린 채 코드만 새 이미지로 교체합니다(제자리 re-exec). Windows 는 아웃오브프로세스 pty-host 로 세션을 유지합니다.

21 · restart-check 드라이런

원격 페더레이션 (ssh)

remote-attach 로 ssh 너머 다른 머신의 pytmux 서버에 붙습니다. 원격 탭은 탭바·외곽선을 분홍색으로 구분하고, 원격 서버가 없으면 분리 서버를 자동 기동합니다. 직접 ssh 가 안 되는 자리는 remote-attach <C> via <B> 로 중간 상자를 거쳐 붙습니다.

34 · 원격 attach

네트워크 응답성 표시 + 회복

클라↔서버 IPC 지연이 커지면 패널 외곽선을 빨간색으로 표시하고, 고착되면 reconnect(또는 워치독 자동)으로 실행 중 셸 / Claude 를 죽이지 않고 IPC 만 다시 세워 반응성을 회복합니다.

16 · 응답성 저하 표시

Plugins · delete-to-disable

디렉토리를 지우면 기능이 사라집니다

시계·달력·디렉토리 트리·IME 배지·Claude 통합·토큰 화면이 모두 한 디렉토리로 응집된 플러그인입니다.

시계 · 달력시계 클릭 → 시계 모드, 날짜 클릭 → 달력 오버레이

ncd 디렉토리 트리루트→cwd 펼침, speed search, Enter 로 cd

IME 한/영 배지OS 입력기 상태를 커서줄에 표시

프롬프트 히스토리보낸 프롬프트 미리보기·검색·점프

Perforce CL 목록변경 목록 조회 · describe

통합 설정 팝업:settings 카테고리별 설정 화면

Download · GitHub

내려받기

소스는 GitHub 에 공개되어 있습니다. 클론하거나 zip 으로 받아 바로 실행하세요.

📦

GitHub 저장소 소스 · 이슈 · 위키(매뉴얼·갤러리·플러그인 가이드) github.com/neoocean/pytmux ↗

⬇️

zip 다운로드 파이썬 TUI 한 벌 — 쓰는 데 필요한 것은 이것이 전부입니다(약 3.5MB) python-tui.zip ↗

📖

위키 · 매뉴얼 설치 · 사용 매뉴얼 · 화면 갤러리 · 플러그인 작성 /wiki ↗

git 으로 클론해서 바로 실행 — 아래 명령만 복사하면 됩니다.

git clone https://github.com/neoocean/pytmux.git cd pytmux pip install -r requirements.txt python3 pytmux.py

GUI 클라이언트도 있지만, 아직 알파입니다 — 실제 작업에는 위의 파이썬 TUI 를 권합니다. pytmux 에는 같은 서버에 붙는 창으로 뜨는 클라이언트(pytmux-gui)가 함께 개발되고 있습니다. 소스와 미리 빌드한 실행 파일은 저장소에 들어 있지만 아직 빠진 조작과 거친 자리가 남아 있어, 구경·시험 용도로 봐 주세요.
목표와 지금 화면은 GUI 클라이언트 소개에 정리해 두었습니다.

Get started

설치는 한 줄, 실행도 한 줄

파이썬만 있으면 됩니다. Python 3.11 이상 권장.

① 의존성 설치 (Textual · wcwidth). Windows 는 pip install pywinpty 도 추가합니다.

pip install -r requirements.txt

② 실행 — 서버가 없으면 자동 기동 후 attach 합니다.

python3 pytmux.py

③ pytmux 명령으로 등록(선택). 등록하면 어디서든 호출할 수 있습니다. OS 에 맞는 설치 스크립트를 실행하세요.

macOS · Linux

./install.sh

Windows (PowerShell)

.\install.ps1

pytmux pytmux ls pytmux cmd new-tab

pytmux 는 attach(없으면 기동), pytmux ls 는 탭/패널 요약, pytmux cmd new-tab 은 외부에서 서버를 제어합니다.

외우지 않아도 되는 터미널 멀티플렉서