tmux나 screen에서 쓰는 Claude Code: detach된 세션에서 알림 받기

01attach 상태: tmux로 알림 통과시키기

tmux는 Claude Code와 terminal 사이에 있으면서, 기본적으로 Claude Code가 데스크톱 알림에 쓰는 escape sequence를 삼켜버려요. Anthropic의 terminal 가이드에서는 ~/.tmux.conf에 다음 설정을 넣으라고 안내해요.

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

실행 중인 서버에 적용하세요.

tmux source-file ~/.tmux.conf

allow-passthrough는 알림과 진행 상황 업데이트가 바깥 terminal까지 전달되게 해줘요. 나머지 줄은 Shift+Enter 줄바꿈 문제를 해결해요. 이렇게 설정하면 tmux 밖에서 Claude Code 알림을 표시하는 terminal(Ghostty, Kitty, 알림을 켠 iTerm2)은 tmux 안에서도 알림을 표시해요.

terminalSequence를 반환하는 hook도 마찬가지예요. Anthropic의 hooks 레퍼런스에 따르면 이 sequence는 Claude Code가 직접 출력하기 때문에 tmux와 GNU screen 안에서도 동작해요. 예시는 macOS, Linux, SSH 가이드에 있어요.

02attach 상태지만 다른 window에 있을 때: bell 사용하기

Claude Code를 한 tmux window에서 실행하고 다른 window에서 작업한다면 bell이 간단한 신호가 돼요. Claude Code가 항상 bell을 보내도록 설정하세요.

{
  "preferredNotifChannel": "terminal_bell"
}

그다음 ~/.tmux.conf에서 tmux가 bell에 반응하도록 설정하세요.

setw -g monitor-bell on
set -g bell-action other
set -g visual-bell off

monitor-bell(기본값 on)은 bell이 울린 window를 표시하고, tmux는 상태 표시줄에 !로 표시해요. bell-action other는 지금 보고 있지 않은 window의 bell을 terminal로 전달해서 terminal이 소리를 내거나 아이콘을 튕기게 해요. 현재 window까지 포함하려면 any를 쓰세요. visual-bell을 on으로 설정하면 bell을 전달하는 대신 tmux에 메시지를 표시해요.

03어떤 세션이 확인이 필요한지 알리기

세션을 여러 개 돌리고 있으면 "Claude가 확인을 기다려요"라는 알림만으로는 별 도움이 안 돼요. hook은 pane의 환경 안에서 실행되므로 tmux에 세션과 window 이름을 물어볼 수 있어요. 다음 Linux 예시는 이 이름을 데스크톱 알림에 표시해요.

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
where=""
if [ -n "$TMUX_PANE" ]; then
  where=$(tmux display-message -p -t "$TMUX_PANE" '#S:#W')
fi
notify-send "Claude Code ${where}" "$msg"

~/.claude/hooks/notify-tmux.sh로 저장하고 chmod +x를 실행한 뒤 Notification 또는 Stop hook 명령으로 사용하세요. #S는 세션 이름, #W는 window 이름이에요. tmux new -s api-refactor처럼 세션에 이름을 붙여두면 알림만 보고 어디로 가야 할지 알 수 있어요. notify-send는 사용하는 플랫폼의 명령이나 push로 바꾸면 돼요. 세션을 구분하는 다른 방법은 여러 세션 가이드를 참고하세요.

04detach 상태: push가 필요해요

detach야말로 tmux를 쓰는 이유죠. 긴 작업을 시작하고 detach한 뒤 자리를 뜨면 돼요. Claude Code는 detach된 세션에서 계속 작업해요. 하지만 이제는 escape sequence나 bell을 보여줄 terminal이 없고, tmux 서버를 SSH로 시작했다면 데스크톱 알림 명령도 전달될 곳이 없을 수 있어요.

네트워크 요청을 보내는 hook은 누가 attach해 있든 상관없이 동작해요. 어떤 push 서비스든 괜찮아요. ntfy 가이드와 Telegram, Slack, Discord 가이드에 바로 붙여넣을 수 있는 hook이 있어요. 다만 이런 알림은 무슨 일이 생겼는지 알려줄 뿐 Claude에게 응답할 수는 없어서, 권한 prompt는 tmux attach -t api-refactor로 다시 attach할 때까지 기다려요.

05Claude Code Notifier의 역할

Claude Code Notifier는 Claude Code의 hook을 기반으로 만든 독립 도구예요(Anthropic이 아닌 TouchTap이 만들었어요). 무료 커맨드라인 도구인 ccn은 Mac, Windows, Linux에서 실행돼요. terminal이 아니라 Claude Code에 hook으로 연결되기 때문에 tmux, screen, 일반 셸 어디서든, attach 여부와 상관없이 똑같이 동작해요.

curl -fsSL https://claudecodenotifier.com/install.sh | sh

데스크톱 머신에서는 Claude가 작업을 마치거나, 권한이 필요하거나, 질문할 때 데스크톱 알림을 표시해요. 폰을 페어링하면 같은 이벤트가 TouchTap의 암호화된 relay를 거쳐 push 알림으로 도착해요. SSH로 접속한 서버를 포함해 ccn이 실행되는 모든 머신에서요.

detach된 세션의 빈틈은 폰이 메워줘요. 권한 요청이 오면 폰에서 한 번 허용, 세션 동안 허용, 거부를 선택할 수 있고, 다시 attach하지 않아도 Claude가 작업을 이어가요. Claude가 질문하면 답을 고를 수 있고, Claude가 작업을 마치면 바로 다음 지시를 보낼 수 있어요. 최근 30초 안에 입력한 적이 있다면 폰을 기다리지 않고 terminal이 평소처럼 물어봐요. 자리를 비운 동안에는 terminal이 직접 정한 최대 시간(hold_ceiling_seconds)까지 폰의 응답을 기다리고, 키보드를 건드리는 순간 기다림을 멈춰요.

폰 페어링하기, 긴 작업 맡겨두고 자리 비우기, ccn 페이지를 참고하세요. 폰 앱은 구독 또는 평생 이용권 구매가 필요해요. 요금제를 확인하세요.

06GNU screen

이 부분에서 screen은 tmux와 거의 비슷하게 동작해요. Anthropic의 hooks 레퍼런스에 따르면 hook의 terminalSequence 출력은 screen 안에서도 동작하고, screen은 보고 있지 않은 window에서 bell이 울리면 메시지를 표시해요. detach된 screen 세션도 detach된 tmux와 같은 문제가 있어요. 화면에 아무것도 없으니 push를 사용하세요.

07FAQ