# hivemux 동작 원리 - tmux 와 Claude Code 훅

hivemux 동작 원리입니다. Claude Code 훅 열한 개가 세션 상태를 tmux 칸에 기록하고 사이드바가 1초마다 읽으며, 재부팅하면 tmux-resurrect 와 claude --resume 으로 세션을 복원합니다. 개인정보와 네트워크 접근도 다룹니다.

Source: https://hivemux.dev/ko/docs/how-it-works/

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 알림](/ko/guides/claude-code-notifications/)에 있습니다.

## 상황별 유지 범위

| 상황 | 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 세션 재개](/ko/guides/resume-claude-code-sessions/)에 있습니다.

## 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](/ko/guides/claude-code-tmux/)에 있습니다.