Python · Textual · 단일 서버 / 다중 클라이언트

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

tmux 처럼 하나의 터미널을 여러 패널·탭으로 나눠 쓰되, 마우스·메뉴를 1급으로 지원합니다. 앱을 닫아도 셸은 살아 있고, Claude Code 토큰 사용량을 한눈에 보여주고 전송 오류로 멈추면 자동으로 다시 잇습니다. macOS · Linux · Windows 네이티브.

설치하고 시작하기 최신버전 zip 다운로드 ⬇ GitHub 에서 보기 ↗ 상세 가이드 →
pytmux — 하나의 터미널을 좌우 패널로 분할한 화면. 활성 패널은 파란 테두리.
Changelog

최근 수정사항

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

🛠 최근 수정사항 · 2026-10-02 금요일 전체 변경 내역 →
  • 설정 설정 화면에서 바꾼 값과 프롬프트로 건 명령이 «적힌 그대로» 먹습니다. 설정 화면·설정 파일·명령 프롬프트가 같은 옵션을 서로 다르게 다루던 자리를 맞췄습니다(파이썬·GUI 클라이언트).
    • alt-scroll — :settings 에서 바꾸면 설정 파일에 적히는데 다음 시작 때 그 줄을 안 읽어 기본값으로 돌아왔습니다. 이제 남습니다.
    • net-rtt-threshold — 빨간 외곽선(응답 지연) 문턱을 설정 파일의 set net-rtt-threshold <초> 로 바꿀 수 있습니다(기본 0.4초 · 0.05~10). 느린 원격 링크에서 늘 빨갛다면 올립니다.
    • set-hook — 명령 프롬프트로 건 훅이 따옴표를 잃어 run-shell "notify.sh $PYTMUX_ACCOUNT" 가 첫 낱말만 돌았습니다. 이제 설정 파일의 hook 줄과 같은 명령으로 돕니다.
    • :set strip-box-drawing on|off 가 조용히 무시되던 것, layout-list 가 명령 목록·자동완성에 안 뜨던 것을 고쳤습니다.
    설정 화면이 파일에 쓰는 줄은 이제 전부 다음 시작 때 다시 읽히는지 시험이 하나씩 잽니다 — 14. 설정.
  • 토큰 토큰 사용량 판의 경고 빨강이 다시 읽힙니다. 패널 앱의 표준 색을 바로잡던 변경(8월)이 판 자체의 막대·사용률 글자까지 어둡게 만들어, 5시간 한도 97% 같은 경고 값이 판 바탕 위에서 거의 안 보였습니다(대비 1.4:1). 판의 의미색을 GUI 와 같은 색으로 고정해 경고 글자가 4.5:1 이상으로 읽힙니다. 패널 안 앱의 색은 그대로입니다. 토큰 판 스크린샷 3장(기간 · 세션 · 한도)을 다시 찍었습니다 — 9. 토큰 사용량.
  • Claude Claude Code 가 이제 스스로 하는 일 넷을 pytmux 에서 걷었습니다. Claude Code 는 사용량 한도가 풀리면 열린 세션을 스스로 이어 가고(2.1.234~), 대화형 세션을 auto 권한 모드로 시작합니다(2.1.284~). 시작 규칙·피드백 문구·원격 제어 자동 연결도 자기 설정으로 다룹니다. 겹친 채 두면 서로 방해합니다 — 예를 들어 pytmux 가 한도 리셋 시각에 대신 치던 continue 가 Claude Code 의 대기를 끊어 버립니다. 그래서 다음을 없앴고, 각각 대신 쓸 설정을 가이드에 적었습니다.
    • 토큰리밋 자동 재개(prefix R·상태줄 AR·auto-resume) → Claude Code 의 「Continue automatically at usage limit」(기본 켜짐)
    • auto-launch·claude-auto-mode → 기본 auto 모드 · "remoteControlAtStartup": true
    • claude-rules → SessionStart 훅(적어 두었던 규칙은 상태 디렉터리의 …claude-rules.retired.txt 로 한 번 보존됩니다)
    • claude-disable-feedback 플러그인 → "spinnerTipsEnabled": false · "feedbackSurveyRate": 0
    전송 오류 자동 재시도(auto-retry)는 그대로입니다 — Claude Code 는 재시도를 다 쓰면 대화형 턴을 끝내기 때문입니다. 파이썬·GUI 클라이언트 둘 다에 적용됩니다. 자세한 설정은 8. Claude Code 연동.
  • 토큰 토큰 사용량 판에서 Tab·←→ 로 탭을 오가고, [머신] 탭이 기기 이름을 씁니다. 지금까지는 판 안에서 다른 탭으로 가는 길이 클릭과 글자 바로 가기(p·l·o)뿐이었습니다. Tab 은 판을 닫아 버렸고 ←→ 도 세션·머신 탭에서는 판을 닫았습니다(GUI 는 두 키를 삼켰습니다).
    • Tab·Shift+Tab — 언제나 다음·이전 탭으로 옮기고 끝에서 감깁니다. 판은 닫히지 않습니다.
    • ←→ — 그 줄에 다른 뜻이 없을 때 이웃 탭입니다. 기간 트리의 펼침·접힘과 한도 탭 모델·컨텍스트 줄의 값 고르기는 그대로입니다.
    • [머신] 탭 · 요약줄 Σ 분해 · GUI 의 머신 판이 같은 이름을 씁니다 — 등록할 때 붙인 기기 이름(보통 호스트 이름)이고, 동기화 서버가 아직 이름을 내려 주지 않으면 셋 다 기기 id 앞 8자리입니다. 종전에는 같은 기기를 세 자리에서 12자 · 8자 · 32자 전체로 다르게 적었습니다.
    • GUI 판은 탭을 옮겨도 높이가 그대로입니다 — 내용이 짧은 탭으로 가면 판이 줄어들던 것을 고쳤습니다.
    파이썬·GUI 클라이언트가 같은 규칙을 씁니다. 자세한 것은 9. 토큰 사용량.
  • 블록 위로 굴리면 패널 첫 줄에 지금 보는 출력의 명령이 붙고, 블록 요약 판이 파이썬 클라이언트에도 생겼습니다. 긴 출력 한가운데서 「이게 무슨 명령의 출력이었지」를 찾으러 다시 위로 굴릴 필요가 없습니다.
    • 스티키 프롬프트 바 — 굴린 패널 첫 줄에 ▲ 명령 띠가 붙고(Claude 패널이면 그 답을 끌어낸 프롬프트), 띠를 누르면 그 프롬프트 줄로 건너뜁니다. 파이썬·GUI 클라이언트에 같은 날 들어갔고, 어느 줄에 띠를 세울지는 한 벌의 규칙을 같은 사례 표로 맞대어 잽니다.
    • 블록 요약 판(summary) — 활성 패널의 블록을 결과 표식(ok·err 등) · 명령 · 작업 디렉토리로 한 판에 보여 줍니다. GUI 에만 있던 판입니다.
    • 그 맞대기가 기존 결함을 하나 잡았습니다 — 파이썬 클라이언트에서 블록을 고르면 다음 명령의 프롬프트 줄까지 한 줄이 딸려 강조·복사되던 것을 고쳤습니다.
    • (저녁에 고침) 파이썬 클라이언트에서 띠의 명령 글자가 파일 경로처럼 보이면 그 글자를 눌렀을 때 스크롤 대신 경로가 복사되던 것 — 이제 띠는 어디를 눌러도 그 프롬프트로 가고, 띠 글자에는 경로 밑줄도 긋지 않습니다(GUI 와 같은 순서).
    셸 블록은 셸 통합 설정이 있어야 생깁니다 — blocks 플러그인.
  • GUI GUI 의 스크롤바를 끌 수 있고, RTT 그래프가 실제 값으로 그려지며, 알림 이력 판이 정본처럼 움직입니다.
    • 스크롤바 — 보이기만 하던 오른쪽 막대를 잡아 끌어 스크롤하고, 막대 바깥 트랙을 누르면 그 비율 자리로 건너뜁니다.
    • RTT 그래프 — 글자 칸을 8단계로 칠하던 막대를 실제 값에 비례하는 픽셀 막대로 바꿨습니다. 임계는 점선, 측정이 없던 구간은 바닥의 점입니다.
    • 알림 이력 판 — 커서로 고르고 Enter 로 전문을 펼치고 c 로 복사합니다. 꼬리줄 안내도 「아무 키나 닫기」에서 실제 키(↑↓ · Enter · c · Esc)로 바꿨습니다.
    • 상태 판의 PageUp·PageDown 이 정본처럼 5줄씩 움직입니다.
    이로써 두 클라이언트가 다르게 구는 자리를 적어 두는 목록(갈림 대장)의 「할 일」이 0 이 됐습니다 — 남은 갈림은 터미널이 못 주는 키 · 픽셀 그림 · OS 창 통합뿐입니다. GUI 클라이언트 소개.
  • 표시 :set ambiguous-width 가 언제나 서버까지 맞추고, ESC[3J 가 스크롤백도 비웁니다.
    • 모호폭(한글 환경에서 폭이 애매한 글자) 설정은 클라이언트와 서버가 따로 들고 있는데, 둘이 어긋난 채로 클라이언트 값과 같은 값을 고르면 서버에 아무것도 알리지 않았습니다 — 「바꿨는데 화면이 그대로다」로만 보였습니다. 이제 이 명령은 언제나 둘을 그 값으로 맞춥니다(파이썬 클라이언트).
    • /clear 류 명령은 화면 지우기(ESC[2J)와 함께 스크롤백 지우기(ESC[3J)를 보내는데, pytmux 가 뒤엣것을 앞엣것과 똑같이 다뤄 화면은 비었는데 위로 굴리면 옛 대화가 그대로 나왔습니다. 이제 xterm·tmux 처럼 스크롤백까지 비웁니다. 화면 격자는 서버가 관리하므로 파이썬·GUI 클라이언트 둘 다에 적용됩니다.
  • 문서 가이드·플러그인 페이지·위키를 지금 코드와 다시 맞추고(새벽·오후 두 차례), 스크린샷을 다시 찍어 내용이 달라진 것을 갈아 끼우고 새 그림을 더했습니다.
    • 새벽 갱신 — 위에서 걷은 기능을 소개하던 문장을 정리하고, 8장에 남은 Claude 보조 기능을 모은 「설정 팝업과 그 밖의 도움」 절을 새로 넣었습니다.
      • 사실과 달랐던 것 — 공유 격자 크기 window-size 의 기본은 latest, Windows 마우스 이동 전달은 기본 on 입니다. 2장은 없어진 --native 대신 pytmux-gui 를 안내합니다.
      • 14장에 설정 파일의 set 줄이 실제로 읽는 옵션 목록을 적고, 파일에 적어도 읽히지 않는 옵션에는 (런타임) 표시를 달았습니다. 7장의 훅 예시는 따옴표가 지켜지는 설정 파일의 hook 줄로 바꾸고, ESC 모드 표에 c·f·b·Shift+ESC·` 를 더했습니다.
      • 플러그인 페이지는 명령 표를 실제 명령 목록과 맞췄고(claude-usage·claude-auto-yes·claude-auto-redraw 등), 블록 고르기 키 · 녹화 로그 경로 · 한/영 배지 자리(커서 줄 오른쪽 끝)를 바로잡았습니다.
      • 스크린샷은 45장을 새로 찍어 6장만 교체했습니다 — 첫 실행 · 메뉴 2장 · 명령 목록 · Claude 설정 팝업 · 설정 팝업에서 걷은 기능의 항목이 빠졌습니다. 나머지는 박혀 있는 시계·날짜만 달랐습니다.
    • 오후 갱신 — 위의 토큰·블록·GUI 변화를 가이드와 위키 매뉴얼에 옮겼습니다.
      • 9장에 탭 이동 키와 머신 이름을, blocks 플러그인 페이지에 스티키 프롬프트 바 · 요약 판 · 결과 표식 표를, 5장에 스티키 바 안내를 더했습니다. GUI 소개에는 「최근에 맞춘 것」 절을 새로 냈습니다.
      • 위키 매뉴얼은 토큰 판 탭 표가 없어진 탭(계정 · 대사)과 옛 키를 아직 싣고 있어 지금 탭과 키로 고쳤고, 스티키 프롬프트 바 · 블록 요약 판 절과 블록 명령 표를 더했습니다.
      • 스크린샷은 토큰 판 꼬리줄에 Tab 안내가 붙어 2장(기간 · 세션)을 교체했고, 스티키 프롬프트 바 · 블록 요약 판(파이썬 클라이언트)과 GUI 의 스티키 바 컷을 새로 넣었습니다.
전체 변경 내역 →
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 의 상태·토큰·한도를 상태줄과 팝업으로 한눈에.

상태 표시 + 권한 모드

실행 중인 탭에 상태 아이콘(대기 ○ / 처리중 ◐ / 리밋 멈춤 ⊘)을 표시하고, 비활성 탭 작업이 끝나면 탭 배경색으로 알립니다. 전송 오류로 멈추면 "계속" 을 넣어 이어 갑니다(한도 뒤 이어 가기는 Claude Code 가 스스로 합니다).

  • 권한모드 footer 클릭 → auto / accept / default / plan 선택
  • 진행을 막는 화면(조직 관리설정 승인)은 기본 선택 그대로 자동 통과
권한 모드 선택 팝업
13 · 권한 모드 선택

토큰 사용량 팝업

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

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

실제 Claude 패널에서

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

  • 멀티라인 프롬프트 붙여넣기 · 이미지 붙여넣기 패스스루
  • 프롬프트 히스토리 플러그인으로 보낸 프롬프트 점프
  • CJK 모호폭 자동 감지(:set ambiguous-width auto)와 화면 깨짐 자동 완화(claude-auto-redraw)로 글자 겹침 방지
실제 Claude Code 가 실행 중인 패널
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> 로 중간 상자를 거쳐 붙습니다.

원격 attach 화면
34 · 원격 attach

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

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

응답성 저하 표시
16 · 응답성 저하 표시
Plugins · delete-to-disable

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

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

시계 모드
시계 · 달력시계 클릭 → 시계 모드, 날짜 클릭 → 달력 오버레이
디렉토리 트리 ncd
ncd 디렉토리 트리루트→cwd 펼침, speed search, Enter 로 cd
IME 한영 배지
IME 한/영 배지OS 입력기 상태를 커서줄에 표시
프롬프트 히스토리
프롬프트 히스토리보낸 프롬프트 미리보기·검색·점프
Perforce CL 목록
Perforce CL 목록변경 목록 조회 · describe
통합 설정 팝업
통합 설정 팝업코어 :settings — 플러그인이 자기 설정 카테고리를 끼워 넣습니다
3
macOS · Linux · Windows
2,400+
헤드리스 테스트 통과
1
파이썬 스크립트로 실행
∞
셸 영속 (detach 후 재접속)
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 은 외부에서 서버를 제어합니다.

Contact

만든 사람에게

버그 제보·제안·문의는 GitHub 이슈 또는 메일로 보내 주세요.

✉️ me@woojinkim.org
이슈/기능 요청은 GitHub Issues 가 가장 빠릅니다.