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 로 끝내고 다시 여세요. 실행 중인 작업이 모두 끝나니 주의해야 합니다.

Claude Code tmux 설정과 사용법

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 세션 복구 방법에서 다룹니다.

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

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

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 를 구분하게 해서 줄바꿈 단축키가 동작하게 합니다. 넣은 뒤에는 실행 중인 서버에 적용합니다.

tmux source-file ~/.tmux.conf

2단계. 접두키 변경

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

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

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

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

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

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

hivemux 가 tmux 에 더하는 것

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

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 입니다.

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

hm ~/code/api

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

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

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

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