macOS에서 Claude Code 알림 받기

01Claude Code의 기본 동작

Claude Code는 작업을 마치거나 권한을 기다리는데 사용자가 터미널을 떠난 것 같으면 알림 이벤트를 발생시켜요. Anthropic의 터미널 가이드에 따르면 실제로 보이는 건 터미널마다 달라요:

iTerm2에서는 Settings > Profiles > Terminal을 열고 Notification Center Alerts를 체크한 다음, Filter Alerts를 클릭해 Send escape sequence-generated alerts를 켜세요. 시스템 설정 > 알림에서 iTerm2의 알림이 허용되어 있는지도 확인하세요.

Apple Terminal에서는 최소한 소리는 받을 수 있어요. ~/.claude/settings.json에 "preferredNotifChannel": "terminal_bell"을 설정하고 Settings > Profiles > Advanced에서 Audible bell을 켜세요. 자세한 방법은 터미널 벨 가이드를 참고하세요.

기본 알림에는 한계가 있어요. Claude Code가 사용자가 자리를 비웠다고 판단할 때만 울리고, 무슨 일이 있었다는 것만 알려주며, 컴퓨터 밖으로는 전달되지 않아요.

02osascript로 만드는 알림 hook

Hook은 IDE 터미널을 포함해 모든 터미널에서 동작해요. 아래는 Anthropic의 hooks 가이드에 있는 macOS 예시예요. 기존 키는 그대로 두고 ~/.claude/settings.json에 추가하세요:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Claude Code에서 /hooks를 입력해 Notification 아래에 표시되는지 확인하세요.

스크립트 편집기 권한

osascript는 스크립트 편집기 이름으로 알림을 보내요. 스크립트 편집기에 알림 권한이 없으면 명령이 조용히 실패하고 macOS도 권한을 묻지 않아요. 터미널에서 한 번 실행해 보세요:

osascript -e 'display notification "test"'

처음에는 아무것도 뜨지 않아요. 시스템 설정 > 알림을 열고 스크립트 편집기를 찾아 알림 허용을 켜세요. 명령을 다시 실행하면 테스트 알림이 표시될 거예요.

실행 시점

빈 matcher는 모든 알림 유형에 반응해요. 가장 중요한 두 가지는 permission_prompt(Claude가 승인을 약 6초간 기다렸는데 입력이 없을 때)와 idle_prompt(Claude가 약 60초 전에 작업을 마쳤는데 그 뒤로 입력이 없을 때)예요. 모든 유형과 타이밍은 Notification hook 가이드에 정리되어 있어요.

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

idle_prompt는 1분을 기다려요. 바로 알림을 받으려면 Claude가 턴을 마칠 때 실행되는 Stop hook을 추가하세요. Stop에는 matcher가 없어요:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

sound name에는 Glass, Ping, Hero처럼 /System/Library/Sounds에 있는 아무 사운드나 쓸 수 있어요. 소리만 원한다면 명령으로 afplay /System/Library/Sounds/Glass.aiff를 써도 돼요. 이 이벤트에 대한 자세한 내용은 Stop hook 가이드를 참고하세요.

04실제 메시지 표시하기

Hook은 표준 입력으로 JSON을 받아요. Notification 입력에는 "Claude needs your permission" 같은 message 필드가 있어요. 간단한 스크립트로 이 텍스트를 알림에 넣을 수 있어요. 다음 내용을 ~/.claude/hooks/notify-mac.sh로 저장하세요:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
osascript -e 'on run argv' \
  -e 'display notification (item 1 of argv) with title "Claude Code"' \
  -e 'end run' "$msg"

텍스트를 AppleScript 문자열 안에 넣지 않고 인자로 넘기기 때문에 메시지에 따옴표가 있어도 명령이 깨지지 않아요. chmod +x ~/.claude/hooks/notify-mac.sh로 실행 권한을 주고 hook 명령을 ~/.claude/hooks/notify-mac.sh로 설정하세요. 스크립트에는 jq가 필요해요(jq --version이 실패하면 brew install jq).

05terminal-notifier: 클릭하면 터미널로 돌아가기

osascript 알림을 클릭하면 스크립트 편집기가 열리는데, 원하는 동작은 아니죠. terminal-notifier를 쓰면 앞으로 가져올 앱을 지정할 수 있어요:

brew install terminal-notifier
terminal-notifier -title "Claude Code" -message "Claude has finished" -sound default -activate com.googlecode.iterm2

Apple Terminal은 com.apple.Terminal을, 에디터라면 해당 앱의 bundle ID를 쓰세요. 같은 명령을 hook의 command 필드에 넣으면 돼요. 처음 한 번은 시스템 설정에서 terminal-notifier의 알림을 허용하세요.

06집중 모드와 방해 금지

모두 일반적인 macOS 알림이라 집중 모드에서 숨겨질 수 있어요. 특정 시간대에 알림이 사라진다면 시스템 설정 > 집중 모드에서 알림을 보내는 앱(스크립트 편집기, terminal-notifier 또는 사용 중인 터미널)을 허용하세요. 원하는 시간대를 따르는 알림이 필요하다면 조용한 시간과 방해 금지를 참고하세요.

07Claude Code Notifier의 역할

Mac 앞에 앉아 있고 가볍게 알림만 받고 싶다면 위의 hook으로 충분해요. 하지만 자리를 비우면 부족해져요. Mac 알림은 부엌에 있는 나에게 닿지 않고, Claude에게 답할 수도 없으니까요.

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

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

또는 Homebrew로 설치할 수도 있어요: brew trust --formula touch-tap/tap/ccn && brew install touch-tap/tap/ccn. ~/.claude/settings.json에 자체 hook 항목을 추가하고, 파일의 나머지 부분은 건드리지 않으며, 백업도 남겨요. 그 뒤로는 Claude가 작업을 마치거나, 권한이 필요하거나, 질문을 할 때 macOS 알림을 보여줘요. 네트워크도 휴대폰도 필요 없어요.

iPhone이나 Android 휴대폰을 페어링하면 같은 이벤트가 push 알림으로 오고, 휴대폰에서 권한을 허용하거나 거부하고, Claude의 질문에 답을 고르거나, 다음 지시를 보낼 수 있어요. 최근 30초 안에 입력했다면 평소처럼 터미널에서 묻고 휴대폰에서는 기다리지 않아요. 휴대폰 페어링과 ccn 페이지를 참고하세요. 휴대폰 앱은 구독 또는 평생 이용권 구매가 필요해요. 가격을 확인하세요.

ccn을 추가한다면 직접 만든 osascript hook은 제거하세요. 그렇지 않으면 이벤트마다 알림이 두 번 떠요. 예전 Mac 메뉴 막대 앱도 있는데, 같은 Mac에서 ccn과 함께 실행하지 마세요.

08FAQ