hivemux 문제 해결 - Claude Code 와 tmux

먼저 hivemux doctor 를 실행합니다. 필요한 프로그램, tmux·Ghostty 설정 블록, Claude Code 훅 열한 개, 실행 중인 tmux 서버를 점검합니다. 그 밖의 문제는 대부분 사이드바를 다시 띄우거나(hivemux-sidebar respawn) Ghostty 를 완전히 종료했다가 다시 열면 해결됩니다. 증상별 해결 방법은 아래에 있습니다.

자주 쓰는 명령

hivemux doctor                     # 의존성과 연결 점검
hivemux-panes list                 # 재부팅 후 재개할 칸 목록
tmux set -g @hivemux-anim off      # 애니메이션 끄기 (계속 끄려면 메뉴 → 설정)
tmux set -g @hivemux-fps 15        # 애니메이션 프레임 줄이기, CPU 절약 (기본 30)
hivemux-sidebar respawn            # 모든 사이드바 다시 띄우기
touch ~/tmux_no_auto_restore       # 다음 시작 때 복원 건너뛰기

재부팅 후 복원 문제

재부팅 후 Claude 가 다시 열리지 않음

기억 중인 목록과 재개 기록을 먼저 확인합니다. 목록에 없으면 마지막 저장 뒤에 시작했거나 /exit 로 끝낸 세션입니다.

hivemux-panes list
cat ~/.local/share/hivemux/panes.log

기록에 busy 가 있으면 그 칸이 셸 프롬프트가 아니어서 건너뛴 것입니다. pane missing 이면 배치가 바뀌어 칸이 없어진 것입니다. 두 경우 모두 그 폴더에서 claude -c 로 마지막 대화를 이어 가면 됩니다.

방금 만든 창이 복원 목록에 없음

자동 저장은 5분마다 일어납니다. 중요한 작업을 시작했다면 prefix Ctrl+S 로 바로 저장합니다.

복원 없이 깨끗하게 시작

# 다음 시작 때 복원 끄기. 파일을 지우면 다시 켜짐
touch ~/tmux_no_auto_restore
# 배치만 복원하고 Claude 는 재개하지 않기 (tmux 서버가 떠 있을 때)
tmux set-environment -g HIVEMUX_NO_RESUME 1

사이드바 문제

사이드바에 Claude 가 없거나 상태가 늦게 바뀜

사이드바는 Claude Code 훅이 기록한 값을 1초마다 읽습니다. hivemux 설치 전에 시작한 Claude 는 다음 프롬프트를 보내거나 도구를 실행하면 나타납니다. tmux 밖에서 실행한 Claude 는 표시되지 않습니다.

# 사이드바 내용을 글자로 보기
hivemux-agents list

사이드바가 없거나 폭이 이상함

prefix b 를 두 번 누르면 모든 창의 사이드바를 다시 만듭니다. 폭은 오른쪽 클릭 메뉴 → 설정 → 사이드바 폭에서 바꾸거나, 사이드바 오른쪽 끝의 핸들 막대를 끌어서 바꿉니다. 기본 폭은 32칸입니다. 명령으로 바꾸려면 아래처럼 합니다.

tmux set -g @hivemux-sidebar-width 40
hivemux-sidebar fix
# 저장한 폭을 지우고 기본 32칸으로
rm ~/.local/share/hivemux/sidebar-width
# 사이드바가 멈췄거나 이상하면 모두 다시 띄우기
hivemux-sidebar respawn

입력 초점이 사이드바로 옮겨졌다면 q 나 Esc 를 누르면 작업 칸으로 돌아갑니다.

팝업이 뜨면 창 목록에 · 창이 생김

이름 바꾸기, 새 프로젝트, 설정, Option+O, Option+W 팝업은 지금 화면을 멈춘 사본 위에 뜹니다. · 창이 그 사본이고, 팝업을 닫으면 사라집니다.

애니메이션 끄기

오른쪽 클릭 메뉴 → 설정에서 애니메이션을 끄면 바로 멈추고 재시작 뒤에도 꺼져 있습니다. 이번만 끄거나 CPU 사용을 줄이려면 아래 명령을 씁니다.

tmux set -g @hivemux-anim off
# 끄지 않고 프레임만 줄이기 (기본 30)
tmux set -g @hivemux-fps 15

키 문제

Option+숫자를 눌러도 이동하지 않음

Ghostty 가 Option 키를 Alt 로 보내야 합니다. hivemux setup 이 이 설정을 넣지만, 그 전부터 켜 둔 Ghostty 는 완전히 종료하고 다시 열어야 합니다. 그동안은 prefix Space 를 쓰거나 카드를 클릭합니다.

Shift+Enter 가 줄바꿈 대신 전송됨

tmux 서버에 확장 키 설정이 아직 적용되지 않은 상태입니다. 설정을 다시 읽거나 Ghostty 를 새로 엽니다. Ctrl+J 는 언제나 줄바꿈합니다.

tmux source-file ~/.tmux.conf

알림 문제

작업이 끝나도 알림이 뜨지 않음

지금 보고 있는 창의 작업은 알리지 않습니다. 터미널이 뒤에 있거나 다른 창에 있을 때만 뜹니다. 다음을 확인합니다.

• 오른쪽 클릭 메뉴 → 설정에서 알림이 켜져 있는지
• 시스템 설정 → 알림에서 Ghostty(쓰는 터미널)가 허용되어 있는지
• 쓰는 터미널이 Ghostty 처럼 OSC 777 터미널 알림을 지원하는지
• 사이드바가 숨겨져 있지 않은지. 알림은 사이드바가 보내므로 prefix b 로 숨기면 오지 않습니다.

mosh 로 붙은 원격 작업은 알림을 보내지 못하니, 알림이 필요하면 ssh 로 연결합니다. 자세한 내용은 Claude Code 알림에 있습니다.

터미널과 tmux 문제

tmux 안에서 claude 명령을 찾지 못함

tmux 서버는 처음 띄운 환경의 PATH 를 물려받습니다. Ghostty 가 아닌 곳에서 서버를 먼저 띄웠다면 PATH 에 Claude 가 없을 수 있습니다. 서버를 끝내고 Ghostty 로 다시 엽니다.

tmux kill-server

주의

tmux kill-server 는 tmux 안에서 실행 중인 모든 작업을 끝냅니다.

Ghostty 새 탭이 같은 화면을 보여 줌

새 탭은 다른 탭에 표시되지 않은 세션에 붙고, 모든 세션이 이미 표시 중이면 새 세션을 만듭니다. 원하는 세션으로 옮기려면 prefix s 를 씁니다.

Option+O 로 파일이 열리지 않음

Option+O 는 실제로 있는 파일만 최근 것부터 보여 주고, 상대 경로는 Claude 의 작업 폴더 기준으로 찾습니다. 다른 Mac 에서 붙은 화면에서 VS Code 와 Cursor 는 원격 SSH 로 파일을 여는데, 접속한 쪽 Mac 에 Remote - SSH 확장이 있어야 합니다. ⌘+클릭 은 Claude 가 경로를 링크로 출력할 때만 됩니다.

폰과 Remote Control 문제

폰 앱에 세션이 보이지 않음

Remote Control 은 claude.ai 구독 로그인이 필요하고 API 키로는 안 됩니다. Remote Control 을 켜기 전에 시작한 세션은 자동으로 연결되지 않으니 그 세션에서 /remote-control 을 입력합니다.

claude auth status

폰에서 새 세션 버튼이 없음

새 세션은 서버 모드 창이 있어야 만들 수 있습니다. 그 폴더에서 prefix Shift+R 을 누릅니다. 처음에는 Remote Control 사용과 폴더 신뢰를 묻는데 둘 다 y 로 답합니다.

다른 Mac 연결 문제

mosh 가 “Nothing received from server on UDP port” 에서 멈춤

상대 Mac 의 방화벽에서 mosh-server 의 수신 연결을 허용합니다. 두 Mac 모두 brew install mosh 가 필요합니다. 자세한 내용은 다른 Mac 에서 이어서 작업에 있습니다.

설정 되돌리기

hivemux uninstall 은 hivemux 가 추가한 것만 지웁니다. 설치 때 바꾼 파일의 원본은 백업 폴더에 시각과 함께 저장되어 있습니다. 자세한 내용은 제거에 있습니다.

hivemux uninstall
ls -la ~/.local/share/hivemux/backups/