# hivemux 문제 해결 - Claude Code 와 tmux

hivemux 에서 자주 생기는 문제의 증상별 해결 방법입니다. 재부팅 후 Claude 미복원, 사이드바 없음, 알림 안 옴, Option+숫자 안 됨, Shift+Enter 전송, tmux 에서 claude 명령을 못 찾는 문제 등을 다룹니다.

Source: https://hivemux.dev/ko/docs/troubleshooting/

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

## 자주 쓰는 명령

```sh
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` 로 끝낸 세션입니다.

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

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

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

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

### 복원 없이 깨끗하게 시작

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

## 사이드바 문제

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

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

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

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

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

```sh
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 사용을 줄이려면 아래 명령을 씁니다.

```sh
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` 는 언제나 줄바꿈합니다.

```sh
tmux source-file ~/.tmux.conf
```

## 알림 문제

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

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

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

mosh 로 붙은 원격 작업은 알림을 보내지 못하니, 알림이 필요하면 ssh 로 연결합니다. 자세한 내용은 [Claude Code 알림](/ko/guides/claude-code-notifications/)에 있습니다.

## 터미널과 tmux 문제

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

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

```sh
tmux kill-server
```

:::caution
`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` 을 입력합니다.

```sh
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 에서 이어서 작업](/ko/docs/another-mac/)에 있습니다.

## 설정 되돌리기

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

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