SSH로 접속한 원격 서버의 Claude Code에서 알림 받기

01SSH에서 로컬 알림 명령이 동작하지 않는 이유

hook은 Claude Code가 실행 중인 머신에서 Claude Code가 실행하는 명령이에요. SSH로 접속한 서버라면 그 머신은 서버예요. 서버에서 notify-send를 쓰려면 데스크톱 알림 데몬이 있어야 하는데, Anthropic의 hooks 가이드에 따르면 headless 서버나 SSH 세션에는 이 데몬이 없어요. osascript나 PowerShell 토스트 알림은 아예 쓸 수 없고요.

그래서 문제는 "어떤 알림 명령을 쓸까"가 아니라 "신호가 서버에서 나한테 어떻게 전달될까"예요. 방법은 세 가지가 있어요.

02방법 1: SSH terminal로 알림 받기

Claude Code의 기본 알림은 terminal에 출력되는 이스케이프 시퀀스예요. Anthropic의 terminal 가이드에 따르면 이 시퀀스는 SSH를 통해 로컬 머신까지 전달되기 때문에 원격 세션에서도 알림을 받을 수 있어요. Ghostty와 Kitty는 별도 설정 없이 데스크톱 알림 센터로 넘겨줘요. iTerm2는 설정을 켜야 해요. Settings > Profiles > Terminal에서 Notification Center Alerts를 체크하고, Filter Alerts에서 Send escape sequence-generated alerts를 켜세요.

사용하는 terminal이 여기에 없거나 알림 문구를 직접 정하고 싶다면, hook이 이스케이프 시퀀스를 반환하고 Claude Code가 이를 출력하게 할 수 있어요. hook에는 자체 terminal이 없으므로 terminalSequence 필드로 반환해요. 서버에 다음 내용을 ~/.claude/hooks/notify-ssh.sh로 저장하세요.

#!/bin/bash
body=$(jq -r '.message // "Claude Code needs your attention"')
# OSC 9 for iTerm2, WezTerm and ConEmu; use '\033]777;notify;%s;%s\007' for Ghostty
seq=$(printf '\033]9;%s\007' "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

그런 다음 서버의 ~/.claude/settings.json에 추가하세요.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/notify-ssh.sh" }
        ]
      }
    ]
  }
}

chmod +x ~/.claude/hooks/notify-ssh.sh를 실행하고 서버에 jq를 설치하세요. Anthropic의 레퍼런스에 지원되는 시퀀스가 나와 있어요: OSC 9(iTerm2, ConEmu, Windows Terminal, WezTerm), OSC 99(Kitty), OSC 777(urxvt, Ghostty, Warp), 그리고 단순 벨이에요. Claude Code는 인터랙티브 세션에서 인터페이스가 화면에 떠 있을 때만 시퀀스를 출력해요.

구조적인 한계도 있어요. SSH 연결이 끊기거나, 노트북이 잠자기 모드에 들어가거나, 탭을 닫으면 알림이 오지 않아요. tmux에서 Claude Code를 실행한다면 서버의 ~/.tmux.conf에 set -g allow-passthrough on을 추가하세요. 자세한 내용과 detach된 세션 처리는 tmux 가이드에서 다뤄요.

03방법 2: 서버에서 push 보내기

push는 terminal에 의존하지 않기 때문에 오래 걸리는 작업에 적합해요. hook이 서버에서 HTTPS 요청을 보내면 서비스가 휴대폰이나 채팅으로 전달해 줘요. ntfy 가이드와 Telegram, Slack, Discord 가이드에 바로 쓸 수 있는 hook이 있어요. 다만 무언가 일어났다는 것만 알려 줄 뿐, 명령을 승인하거나 질문에 답할 수는 없어서 Claude는 다시 접속할 때까지 기다려요.

04방법 3: 서버에 Claude Code Notifier 설치하기

Claude Code Notifier는 독립 도구예요(Anthropic이 아닌 TouchTap이 만들었어요). 무료 커맨드라인 도구인 ccn은 Mac, Windows, Linux에서 동작하므로 Claude Code가 실행되는 서버에 설치하면 돼요.

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

서버의 ~/.claude/settings.json에 hook 항목을 추가하고, 기존 설정은 그대로 두며 백업도 만들어 줘요. ccn의 데스크톱 알림은 ccn이 실행되는 머신에 표시되기 때문에 헤드리스 서버에서는 쓸모가 없어요. 유용한 건 휴대폰이에요. 휴대폰 알림은 SSH 연결이 아니라 TouchTap의 암호화된 릴레이 서버를 거치므로, 인터넷에 연결되어 있다면 ccn이 실행되는 어떤 머신에서든 동작해요.

SSH에서 페어링하기

페어링에 서버 쪽 브라우저는 필요 없어요. SSH 세션에서 ccn pair를 실행하면 terminal에 QR 코드와 24시간 동안 유효한 링크가 출력되니, 휴대폰 카메라로 QR 코드를 스캔하세요. 아니면 휴대폰에서 앱을 열고 Computers > Add a computer로 이동해 표시된 명령을 실행하세요. 설치와 페어링이 한 번에 끝나요.

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

(여섯 자리 코드는 예시이니 앱에 표시된 코드를 사용하세요.) 휴대폰 하나에 여러 컴퓨터를 연결할 수 있어서 노트북과 서버 모두에서 알림을 받을 수 있어요. 자세한 내용은 페어링 가이드를 참고하세요.

휴대폰에서 할 수 있는 일

페어링하면 Claude가 작업을 마치거나, 권한이 필요하거나, 질문할 때 push를 받아요. 권한 요청은 한 번 허용, 세션 동안 허용, 거부 중에서 고를 수 있고, Claude의 질문에 답을 선택하거나 Claude가 작업을 마친 뒤 다음 지시를 보낼 수도 있어요. 자리를 비운 동안에는 terminal이 직접 정한 최대 시간까지 폰의 응답을 기다리고, 키보드를 입력하는 순간 기다림을 멈춰요. 서버에서 ccn doctor를 실행하면 hook, 자격 증명, relay 연결 상태를 확인할 수 있어요. 폰 앱은 요금제를 참고하세요. 커맨드라인 도구는 무료예요.

05SSH 연결이 끊겨도 Claude Code 유지하기

세 가지 방법 모두 Claude Code 자체가 계속 실행 중이어야 해요. SSH 셸에서 claude를 바로 실행했다면 연결이 끊길 때 세션도 함께 종료돼요. 연결이 끊겨도 살아남도록 tmux나 GNU screen 안에서 실행하고, 나중에 다시 attach하세요. detach된 세션에서도 hook은 계속 실행되기 때문에, 이때 폰 push가 진가를 발휘해요. 이 워크플로는 tmux 가이드와 긴 작업 맡겨두고 자리 비우기에서 다뤄요.

06FAQ