# Claude Code tmux 설정과 사용법

tmux 안에서 Claude Code 를 쓸 때 필요한 설정(접두키, Shift+Enter, 알림 전달)과 세션·창 구성 방법, hivemux 가 tmux 위에 더하는 사이드바를 정리했습니다.

Source: https://hivemux.dev/ko/guides/claude-code-tmux/

> Claude Code 를 tmux 안에서 실행하면 터미널을 닫아도 세션이 계속 돌아가고, 프로젝트마다 tmux 세션을 나눠 여러 작업을 관리할 수 있습니다. ~/.tmux.conf 에 allow-passthrough 와 extended-keys 를 켜야 알림과 Shift+Enter 줄바꿈이 제대로 동작하고, Claude Code 가 Ctrl+B 를 쓰므로 접두키를 Ctrl+A 로 바꾸는 경우가 많습니다. hivemux 는 이 설정을 넣고 모든 창 왼쪽에 Claude 세션 상태판을 붙입니다.

tmux 는 터미널 안에서 세션, 창, 분할을 관리하는 프로그램입니다. Claude Code 처럼 오래 실행되는 프로세스를 tmux 안에 두면 터미널 창을 닫아도 작업이 끝나지 않고, 나중에 다시 붙어서 이어 볼 수 있습니다. 이 글은 tmux 에서 Claude Code 를 쓸 때 필요한 설정과 작업 구성 방법을 먼저 설명하고, hivemux 가 그 위에 무엇을 더하는지 정리합니다.

## tmux 를 쓰는 이유

- **세션 유지:** 터미널을 닫아도 tmux 서버가 Claude 프로세스를 살려 둡니다. `prefix d` 로 화면에서 떼어도 작업은 계속됩니다.
- **프로젝트 분리:** 프로젝트마다 tmux 세션을 하나씩 두고, 그 안에 Claude 창과 셸 창을 나눠 둘 수 있습니다.
- **원격 작업:** ssh 로 붙은 원격 Mac 에서도 같은 tmux 세션에 다시 붙을 수 있습니다. Claude Code 공식 문서도 원격 머신에서 실행할 때는 ssh 연결이 끊겨도 세션이 남도록 tmux 나 screen 안에서 시작하라고 안내합니다.

단, tmux 서버는 재부팅하면 사라집니다. 재부팅 후 복구는 [Claude Code 세션 복구 방법](/ko/guides/resume-claude-code-sessions/)에서 다룹니다.

## 1단계. ~/.tmux.conf 설정

Claude Code 공식 문서는 tmux 안에서 실행할 때 다음 세 줄을 권합니다.

```sh
set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'
```

`allow-passthrough` 는 데스크톱 알림과 진행 표시가 tmux 에 막히지 않고 바깥 터미널까지 가게 합니다. `extended-keys` 두 줄은 tmux 가 Shift+Enter 와 Enter 를 구분하게 해서 줄바꿈 단축키가 동작하게 합니다. 넣은 뒤에는 실행 중인 서버에 적용합니다.

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

## 2단계. 접두키 변경

tmux 의 기본 접두키는 `Ctrl+B` 인데, Claude Code 도 `Ctrl+B` 를 씁니다. 그래서 접두키를 `Ctrl+A` 로 바꾸는 경우가 많습니다.

```sh
set -g prefix C-a
unbind C-b
bind C-a send-prefix
```

## 3단계. 프로젝트별 세션 구성

프로젝트 폴더마다 이름 붙인 tmux 세션을 만들고, 그 안에서 Claude 를 실행합니다.

```sh
tmux new-session -s api -c ~/code/api
claude -n api
```

세션 사이 이동은 `prefix s`(세션 목록), 창 이동은 `prefix` 다음 창 번호로 합니다. 이 방식은 잘 동작하지만, 세션이 늘면 어느 세션의 Claude 가 승인을 기다리는지 보려면 세션을 하나씩 열어 봐야 합니다.

## hivemux 가 tmux 에 더하는 것

hivemux 는 모든 Claude Code 세션을 실행 중·입력 대기·완료 상태로 보여 주고, 나를 기다리는 세션으로 바로 이동하게 해 주는 tmux 사이드바입니다.

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

`hivemux setup` 은 기존 설정 파일을 덮어쓰지 않고 `~/.tmux.conf` 에 표시된 블록만 추가합니다. 위의 extended-keys 와 allow-passthrough 설정이 이 블록에 들어 있고, 권장 키를 고르면 접두키가 `Ctrl+A` 로 바뀌며 `|` 와 `-` 로 화면을 나눌 수 있습니다. tmux-resurrect 와 tmux-continuum 도 받아 오고, Claude Code 훅 열한 개를 등록합니다. 필요한 것은 tmux 3.3 이상, jq, git, python3 입니다.

설치 후에는 프로젝트를 이렇게 엽니다.

```sh
hm ~/code/api
```

폴더 이름으로 tmux 세션이 만들어지고, `1:claude` 창에서 Claude 가 실행되며 `2:shell` 창이 함께 생깁니다. 이미 있는 프로젝트에 `hm` 을 다시 입력하면 새로 만들지 않고 그 세션으로 이동합니다.

[Image: 사이드바 작업 카드의 오른쪽 클릭 메뉴: 이동, 이름 바꾸기, 새 Claude, 새 프로젝트]

모든 창 왼쪽에 붙는 사이드바는 어느 tmux 세션을 보고 있든 모든 세션의 Claude 를 보여 줍니다. 자주 쓰는 키는 다음과 같습니다.

- `Option+1` … `Option+9`: 그 번호 Claude 로 이동 (세션이 달라도)
- `Option+0` 또는 `prefix Space`: 가장 오래 기다린 Claude
- `prefix Shift+C`: 이 폴더에서 이름 붙인 Claude 새 창
- `prefix b`: 사이드바 숨기기 / 보이기

hivemux 를 지우려면 `hivemux uninstall` 을 실행합니다. 추가했던 블록과 훅만 지우고 나머지 tmux 설정은 그대로 둡니다. 키 전체 목록은 [단축키 문서](/ko/docs/keys/), 구성 요소별 역할은 [동작 원리 문서](/ko/docs/how-it-works/)에 있습니다.

## FAQ

### tmux 안에서 Shift+Enter 를 누르면 줄바꿈 대신 전송됩니다.

tmux 가 Shift+Enter 와 Enter 를 구분하지 못하는 상태입니다. ~/.tmux.conf 에 set -s extended-keys on 과 set -as terminal-features 'xterm*:extkeys' 를 넣고 다시 읽으세요. 급하면 Ctrl+J 로 줄바꿈할 수 있습니다.

### tmux 접두키를 왜 Ctrl+A 로 바꾸나요?

tmux 기본 접두키 Ctrl+B 를 Claude Code 도 쓰기 때문입니다. hivemux setup 의 권장 키를 고르면 접두키가 Ctrl+A 로 바뀌고, | 와 - 로 화면을 나눌 수 있습니다.

### tmux 밖에서 실행한 Claude 도 hivemux 사이드바에 보이나요?

보이지 않습니다. hivemux 는 Claude Code 훅이 tmux 칸에 기록한 상태를 읽기 때문에 tmux 안에서 실행한 Claude 만 표시합니다.

### tmux 서버 안에서 claude 명령을 찾지 못합니다.

tmux 서버는 처음 띄운 환경의 PATH 를 물려받습니다. 다른 환경에서 서버를 먼저 띄웠다면 tmux kill-server 로 끝내고 다시 여세요. 실행 중인 작업이 모두 끝나니 주의해야 합니다.