Linux에서 Claude Code 알림 받기

01Claude Code의 기본 동작

Claude가 작업을 마치거나 권한 승인을 기다리는데 사용자가 자리를 비운 것 같으면 Claude Code는 알림 이벤트를 발생시켜요. Anthropic의 terminal 가이드에 따르면 Ghostty와 Kitty는 이를 데스크톱 알림으로 띄우지만, GNOME Terminal, Konsole, VS Code terminal 같은 다른 terminal에서는 아무것도 표시되지 않아요.

대신 어떤 terminal에서든 bell을 울리도록 설정할 수 있어요:

{
  "preferredNotifChannel": "terminal_bell"
}

bell이 어떻게 동작할지는 terminal과 데스크톱 환경에 따라 달라요. 소리가 나거나, 화면이 깜빡이거나, 창이 긴급 상태로 표시될 수 있어요. 자세한 내용은 terminal bell 가이드를 참고하세요. 제대로 된 알림을 원한다면 hook을 사용하세요.

02notify-send 설치하기

설치되어 있는지 확인하세요:

notify-send 'Claude Code' 'test'

명령을 찾을 수 없다면 설치하세요:

sudo apt install libnotify-bin   # Debian, Ubuntu, Mint
sudo dnf install libnotify       # Fedora, RHEL
sudo pacman -S libnotify         # Arch

명령은 실행되는데 아무것도 뜨지 않는다면 알림 데몬이 없는 거예요. GNOME, KDE Plasma, Cinnamon, Xfce에는 포함되어 있어요. Sway, i3, Hyprland 같은 타일링 윈도 매니저를 쓴다면 mako나 dunst 같은 데몬을 직접 설치하고 실행하세요. notify-send는 디스플레이가 아니라 D-Bus를 통해 데몬과 통신하기 때문에 Wayland와 X11 모두에서 동작해요.

03Notification hook

Anthropic hooks 가이드에 나오는 Linux 예제예요. 기존 키는 그대로 두고 ~/.claude/settings.json에 추가하세요:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

Claude Code에서 /hooks를 입력하면 Notification 아래에 표시되는 걸 확인할 수 있어요. matcher가 비어 있으면 모든 알림 유형에서 실행돼요. 주요 유형은 승인 요청 후 입력 없이 약 6초가 지나면 발생하는 permission_prompt와, Claude가 작업을 마치고 약 60초 후 발생하는 idle_prompt예요. 전체 목록은 Notification hook 가이드에 있어요.

04Claude가 끝나는 즉시 알림 받기

idle_prompt는 1분 늦게 와요. Stop hook은 Claude가 턴을 마치자마자 실행되고, matcher가 필요 없어요:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send -a 'Claude Code' 'Claude Code' 'Claude has finished'"
          }
        ]
      }
    ]
  }
}

-a는 데몬에 표시될 앱 이름을 지정해요. 그 밖에 유용한 옵션으로, -u critical을 쓰면 대부분의 데몬에서 직접 닫을 때까지 알림이 화면에 남아 있고, -i dialog-information은 아이콘을 추가해요. 이 이벤트에 대한 자세한 내용은 Stop hook 가이드를 참고하세요.

05실제 메시지를 사운드와 함께 표시하기

hook은 표준 입력으로 JSON을 받고, Notification 입력에는 message 필드가 있어요. 스크립트로 이 텍스트를 보여주고 사운드를 재생할 수 있어요. 다음 내용을 ~/.claude/hooks/notify-linux.sh로 저장하세요:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
notify-send -a 'Claude Code' 'Claude Code' "$msg"
paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true

chmod +x ~/.claude/hooks/notify-linux.sh로 실행 권한을 주고, hook 명령으로 ~/.claude/hooks/notify-linux.sh를 지정하세요. jq는 모든 배포판의 패키지에 있어요. paplay는 PulseAudio와 PipeWire의 PulseAudio 레이어에서 동작하고, 사운드 파일은 freedesktop 사운드 테마(Debian과 Ubuntu에서는 sound-theme-freedesktop)에 들어 있어요. 원하는 .oga나 .wav 파일을 써도 돼요.

06notify-send가 없다면? escape sequence를 쓰세요

terminal이 알림 escape sequence를 지원한다면 hook에서 Claude Code에게 대신 보내 달라고 할 수 있어요. hook에는 자체 terminal이 없으므로 terminalSequence 필드에 sequence를 담아 반환하면 Claude Code가 이를 출력해요. Anthropic 레퍼런스에는 Ghostty, urxvt, Warp용 OSC 777과 Kitty용 OSC 99가 나와 있어요. 예를 들면:

#!/bin/bash
body=$(jq -r '.message // "Needs your attention"')
seq=$(printf '\033]777;notify;%s;%s\007' "Claude Code" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

이 방법은 Claude Code가 실행되는 머신에 데몬이 없어도 돼서, SSH로 접속한 원격 서버에서도 쓸 수 있는 요령이에요.

07셸에서는 notify-send가 되는데 Claude Code에서는 안 될 때

notify-send에는 데스크톱 로그인 세션의 D-Bus 세션 주소가 필요해요. hook은 Claude Code의 환경을 그대로 물려받기 때문에, 데스크톱 terminal에서 Claude Code를 실행했다면 문제없어요. 하지만 SSH, systemd 서비스, 컨테이너, 또는 처음에 SSH에서 시작된 tmux 서버 안에서 Claude Code를 실행했다면 이 주소가 없을 수 있고, 그러면 알림이 어디에도 표시되지 않아요. claude를 실행하는 셸에서 echo $DBUS_SESSION_BUS_ADDRESS를 실행해 보세요. 값이 비어 있다면 그 세션에서는 데스크톱 알림이 뜨지 않아요. 이런 환경은 tmux 가이드와 SSH 가이드에서 다뤄요.

08Claude Code Notifier의 역할

위의 hook들은 머신 앞에서 작업할 때는 좋은 선택이에요. 하지만 자리를 떠나면 알림을 받을 수 없고, 데스크톱 알림으로는 Claude에게 응답할 수도 없어요.

Claude Code Notifier는 Claude Code의 hook을 기반으로 만든 독립 도구예요(Anthropic이 아닌 TouchTap이 만들었어요). 무료 커맨드라인 도구인 ccn은 Mac, Windows, Linux에서 동작해요. Linux에서는:

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

Node.js가 있다면 npx @touchtap/ccn을 써도 돼요. ~/.claude/settings.json에 hook 항목만 추가하고 나머지는 그대로 두며, 백업도 남겨요. 그 후로는 Claude가 작업을 마치거나, 권한이 필요하거나, 질문할 때 Linux 데스크톱 알림을 띄워요. 이 기능은 네트워크도 휴대폰도 필요 없어요. 이벤트마다 몇 밀리초만 실행되고, 백그라운드에 상주하는 프로세스는 없어요.

iPhone이나 Android 휴대폰을 페어링하면 데스크톱이 전혀 없는 머신에서도 같은 이벤트를 push 알림으로 받을 수 있어요. 휴대폰에서 권한을 허용하거나 거부하고, Claude의 질문에 답을 고르고, Claude가 끝나면 다음 지시를 보낼 수도 있어요. 휴대폰 앱은 휴대폰 페어링, ccn 페이지, 요금제를 참고하세요. Linux에서 ccn은 토큰을 본인만 읽을 수 있는 파일에 저장해요.

ccn을 설치했다면 알림이 중복되지 않도록 직접 만든 notify-send hook은 제거하세요.

09FAQ