hivemux 동작 원리 - tmux 와 Claude Code 훅

hivemux 는 여러 층으로 동작합니다. Claude Code 훅이 세션 ID 와 상태를 그 세션의 tmux 칸에 기록하고, 사이드바가 그 상태를 1초마다 읽어 상태판을 그립니다. 터미널을 닫아도 tmux 가 프로세스를 살려 두고, 재부팅하면 tmux-resurrect 가 배치를 복원한 뒤 hivemux 가 칸마다 claude --resume <id> 를 입력합니다. 모든 것이 Mac 안에서 돌아가며 서버는 없습니다.

구성 요소별 역할

층	역할
Ghostty	화면을 그립니다. 모든 창이 hivemux-attach 를 실행해 tmux 에 붙습니다
tmux	터미널을 닫아도 프로세스를 살려 둡니다
tmux-resurrect + continuum	5분마다 배치를 저장하고, 처음 시작할 때 복원합니다
Claude Code 훅	세션 ID 와 상태를 tmux 칸에 기록합니다 (hivemux-hook)
사이드바	그 상태를 1초마다 읽어 상태판을 그립니다 (hivemux-sidebar-view)

Claude Code 훅

hivemux setup 은 ~/.claude/settings.json 에 Claude Code 훅 이벤트 열한 개에 대해 hivemux-hook 을 등록합니다.

SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, PermissionDenied, Notification, Stop, StopFailure, SessionEnd

이벤트마다 그 Claude 가 실행 중인 tmux 칸에 세션 ID, 폴더, 상태를 기록합니다. 상태가 tmux 칸에 저장되므로 tmux 밖에서 실행한 Claude 는 사이드바에 나오지 않고, hivemux 설치 전에 시작한 Claude 는 다음 프롬프트를 보내거나 도구를 실행하면 나타납니다.

알림 방식

작업이 입력을 기다리거나 끝나면 사이드바가 알림을 보냅니다. 지금 보고 있는 작업은 알리지 않습니다. 알림은 터미널 알림 신호(OSC 777)로 보내므로 Ghostty 처럼 이를 지원하는 터미널에서 뜹니다. 사이드바를 숨기면(prefix b) 알림도 오지 않습니다. 자세한 내용은 Claude Code 알림에 있습니다.

상황별 유지 범위

상황	tmux 세션과 배치	Claude 대화
Ghostty 창 닫기	유지	계속 실행
Ghostty 종료	유지	계속 실행
Mac 잠자기 (덮개 닫기)	유지	멈췄다가 이어서 실행
재부팅이나 비정상 종료	마지막 저장에서 복원	자동으로 재개
/exit 나 Ctrl+D 로 종료	창은 남음	재개하지 않음

재부팅 후 복원 순서

1. hivemux-attach: tmux 서버가 없으면 임시 세션으로 서버를 띄웁니다.
2. tmux-resurrect: 마지막 스냅숏에서 세션, 창, 칸, 작업 폴더를 다시 만듭니다.
3. hivemux-panes restore: 저장된 칸과 세션 목록을 읽고, 셸 프롬프트에 있는 칸마다 원래 폴더로 이동해 claude --resume <id> 를 입력합니다.
4. Claude Code: 대화가 열립니다(Remote Control 이 켜져 있으면 다시 등록됩니다).
5. hivemux-attach: 재부팅 전에 마지막으로 보던 세션에 붙습니다.

/exit 로 직접 끝낸 세션은 재개하지 않습니다. 자세한 내용은 Claude Code 세션 재개에 있습니다.

hivemux 가 건드리는 파일

경로	내용
~/.tmux.conf	hivemux 블록: hivemux.tmux 와, 골랐다면 권장 키를 불러옴
~/.config/ghostty/config	hivemux 블록: 모든 Ghostty 창을 hivemux-attach 로 tmux 에 붙임
~/.claude/settings.json	hivemux 훅 열한 개와, 골랐다면 모든 세션 Remote Control
~/.zshrc	git 설치일 때만: hivemux bin 폴더를 PATH 에 추가
~/.local/share/hivemux/	플러그인, 칸과 세션 목록(panes.tsv), 재개 기록(panes.log), 사이드바 폭과 설정, 벌 사무실 창, 설정 백업
~/.local/share/tmux/resurrect/	tmux-resurrect 배치 스냅숏

설정 변경은 # >>> hivemux >>> 와 # <<< hivemux <<< 표시 사이에만 들어가고, hivemux uninstall 은 그 부분만 정확히 지웁니다.

개인정보와 네트워크 접근

hivemux 는 서버도 텔레메트리도 없습니다. Mac 안에서만 동작하며 Claude Code 훅 이벤트와 tmux 상태를 읽습니다. 네트워크 요청은 다음뿐입니다.

• Claude 를 업데이트할 때 최신 Claude Code 버전 확인 (npm 레지스트리 또는 Homebrew API)
• GitHub 에서 hivemux 받기·업데이트, 그리고 설치할 때 tmux-resurrect 와 tmux-continuum 플러그인 받기 (~/.tmux/plugins 에 이미 있으면 받지 않음)
• hivemux connect 로 직접 연결하는 Mac 으로의 ssh·mosh 접속

벌 사무실 창은 127.0.0.1 에서만 듣는 작은 웹 서버와 통신합니다.

tmux 에서 Claude Code 를 쓰는 배경은 Claude Code 와 tmux에 있습니다.