# macOS 에 hivemux 설치하기

curl 한 줄 또는 Homebrew 로 macOS 에 hivemux 를 설치하는 방법입니다. 요구 사항, hivemux setup 이 묻는 세 가지 질문과 바꾸는 설정, 설치 옵션, hivemux 와 Claude Code 업데이트 방법을 정리했습니다.

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

macOS 에서 `curl -fsSL https://hivemux.dev/install.sh | bash` 한 줄로 hivemux 를 설치합니다. Homebrew 를 쓴다면 `brew install esteban-eg-kim/tap/hivemux` 다음에 `hivemux setup` 을 실행합니다. tmux 3.3 이상, jq, git, python3, 로그인된 Claude Code 가 필요하고 터미널은 Ghostty 를 권장합니다.

## 요구 사항

- macOS (Linux 도 동작할 가능성이 높지만 시험하지 않았습니다)
- tmux 3.3 이상, jq, git, python3 (python3 는 Xcode Command Line Tools 에 들어 있습니다)
- 로그인된 [Claude Code](https://code.claude.com)
- [Ghostty](https://ghostty.org) 권장. 다른 터미널에서도 `tmux` 를 직접 실행하면 동작합니다.

빠진 프로그램이 있으면 `hivemux setup` 이 멈추고 알려 줍니다. 아래 명령으로 설치합니다.

```sh
brew install tmux jq git
```

## 설치 스크립트로 설치

```sh
curl -fsSL https://hivemux.dev/install.sh | bash
```

이 주소는 hivemux GitHub 저장소의 `install.sh` 를 내려줍니다. 스크립트는 hivemux 를 `~/.local/share/hivemux/src` 에 받고(이미 있으면 업데이트) `hivemux setup` 을 실행합니다. git 으로 설치하면 setup 이 `~/.zshrc` 의 `PATH` 에 hivemux `bin` 폴더도 추가합니다.

스크립트로 설치하면서 setup 옵션을 넘기려면 `bash -s --` 를 씁니다.

```sh
curl -fsSL https://hivemux.dev/install.sh | bash -s -- --no-keys
```

## Homebrew 로 설치

```sh
brew install esteban-eg-kim/tap/hivemux
hivemux setup
```

## hivemux setup 질문

`hivemux setup` 은 세 가지를 묻고, 기본값은 모두 "예"입니다.

| 질문 | 바뀌는 것 |
|---|---|
| 권장 키 사용 | 접두키 `Ctrl+A` (Claude Code 가 `Ctrl+B` 를 씀), `\|` `-` 분할 |
| Ghostty 를 tmux 에 연결 | Ghostty 설정에 `command = hivemux-attach` |
| 모든 세션 Remote Control | `~/.claude/settings.json` 의 `remoteControlAtStartup` |

그 밖에 다음 일도 합니다.

- tmux-resurrect 와 tmux-continuum 을 받아 옵니다. 이미 `~/.tmux/plugins` 에 있으면 그것을 씁니다.
- `~/.claude/settings.json` 에 Claude Code 훅 열한 개를 등록합니다.
- 벌 사무실 창을 뒤에서 미리 빌드합니다.

바꾸는 내용은 모두 `# >>> hivemux >>>` 와 `# <<< hivemux <<<` 표시 사이에 들어가고, 원래 파일은 `~/.local/share/hivemux/backups/` 에 백업됩니다. `hivemux uninstall` 은 그 블록만 정확히 지웁니다. 자세한 내용은 [제거](/ko/docs/uninstall/)에 있습니다.

## 설치 옵션

| 옵션 | 효과 |
|---|---|
| `--yes` | 묻지 않고 모두 기본값으로 진행 |
| `--no-keys` | tmux 기본 접두키와 키 유지 |
| `--no-ghostty` | Ghostty 를 tmux 에 연결하지 않음 |
| `--no-remote` | 모든 세션 Remote Control 을 켜지 않음 |
| `--lang=en` / `--lang=ko` | 화면 언어 (기본값은 셸 언어) |

언어는 설치한 뒤에도 사이드바 오른쪽 클릭 메뉴 → 설정에서 바꿀 수 있습니다.

## 설치 확인

```sh
hivemux doctor
hivemux version
```

`hivemux doctor` 는 필요한 프로그램, tmux·Ghostty 설정 블록, 훅 열한 개, 실행 중인 tmux 서버, 원격 연결 설정을 점검합니다. 확인이 끝나면 Ghostty 새 창을 열고(또는 `tmux` 실행) [빠른 시작](/ko/docs/quick-start/)으로 넘어갑니다.

:::tip
다른 터미널을 쓴다면 Ghostty 질문에 "아니요"로 답하고 `tmux` 를 직접 실행하면 됩니다. 모든 tmux 창에 사이드바가 생깁니다. Ghostty 를 권장하는 이유는 [Ghostty 에서 Claude Code 쓰기](/ko/guides/claude-code-ghostty/)에 있습니다.
:::

## hivemux 업데이트

```sh
# Homebrew
brew update && brew upgrade hivemux && hivemux setup
# git 설치: 설치 명령을 다시 실행
curl -fsSL https://hivemux.dev/install.sh | bash
```

`hivemux setup` 은 다시 실행해도 안전합니다. 자기가 넣은 블록과 훅만 바꾸고(새 버전에서 훅이 늘 수 있음), 실행 중인 tmux 설정을 다시 읽고 사이드바를 다시 띄웁니다. 쓰던 세션은 그대로입니다. 업데이트 전에 시작한 Claude 는 다시 시작해야 새 훅을 씁니다.

## Claude Code 업데이트

사이드바 오른쪽 클릭 메뉴 → "Claude 업데이트"를 고르거나 아래 명령을 실행합니다.

```sh
hivemux update-claude
```

새 버전이 있는지 먼저 확인하고, 확인을 받은 뒤 Claude Code 를 업데이트합니다(Homebrew 로 설치했으면 brew 로). 그다음 칸마다 Claude 를 새 버전으로 다시 시작하며 대화는 그대로 이어집니다. 일하는 중이거나 나를 기다리거나 화면에 보이는 Claude 는 일이 끝나고 화면에서 벗어났을 때 다시 시작합니다.