Claude Code가 작업을 끝냈을 때 알림 받는 방법

01Claude Code의 기본 동작

Claude Code는 사용자가 terminal을 떠난 것 같으면 이미 알림을 보내려고 해요. 기본적으로 iTerm2, Ghostty, Kitty에서는 데스크톱 알림을 보내고, Apple Terminal에서는 벨 문자를 보낼 수 있으며, 그 외 terminal에서는 아무것도 하지 않아요. iTerm2도 알림 설정을 켜야 알림이 표시돼요.

그래서 VS Code terminal, Warp, Windows Terminal이나 대부분의 Linux terminal을 쓴다면 보통 아무 알림도 오지 않아요. preferredNotifChannel 설정으로 terminal 벨을 강제로 켤 수 있는데, 자세한 내용은 terminal 벨 가이드를 참고하세요. 어떤 terminal에서든 제대로 된 데스크톱 알림을 받으려면 hook이 필요해요.

02필요한 hook 두 가지

Hook은 Claude Code가 세션의 정해진 시점에 실행하는 명령이에요. 여기서 중요한 건 두 가지예요.

Stop이 가장 빨라요. 매 턴이 끝날 때마다 즉시 실행돼요. Notification 유형은 사용자가 자리를 비웠을 때만 동작해요. 키를 입력할 때마다 미뤄지기 때문에 화면을 보고 있는 동안에는 알림이 오지 않아요. Claude가 권한을 요청하는 즉시 신호를 받고 싶다면 대신 PermissionRequest hook을 쓰세요. PermissionRequest 가이드에서 설명해요.

hook의 전반적인 동작 방식(이벤트, matcher, 설정 파일, exit code)은 Claude Code hook 설명을 참고하세요.

03macOS에서 동작하는 설정

~/.claude/settings.json을 열고(없으면 새로 만드세요) 다음 내용을 추가하세요. 파일에 이미 hooks 객체가 있다면 덮어쓰지 말고 그 안에 Stop과 Notification 키를 추가하세요.

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

Stop은 matcher가 없어서 매 턴마다 실행돼요. Notification matcher는 "돌아오세요"라는 의미의 두 유형으로만 범위를 제한해요.

아무것도 뜨지 않는다면 macOS가 Script Editor를 차단하고 있을 수 있어요. osascript는 Script Editor를 통해 알림을 표시해요. Terminal에서 osascript -e 'display notification "test"'를 한 번 실행한 다음, 시스템 설정 > 알림을 열고 Script Editor를 찾아 알림 허용을 켜세요.

04Linux와 Windows에서도 같은 방식으로 설정하기

위의 JSON 구조는 그대로 두고 command 문자열만 바꾸면 돼요.

Linux (데스크톱 알림 데몬이 필요하므로 headless 서버에서는 동작하지 않아요):

"command": "notify-send 'Claude Code' 'Claude has finished'"

notify-send가 없다면 Debian과 Ubuntu에서는 libnotify-bin을, 다른 배포판에서는 그에 해당하는 패키지를 설치하세요. SSH나 서버 환경이라면 SSH에서 알림 받기를 참고하세요.

Windows (PowerShell). Anthropic의 공식 예제는 화면 모서리의 토스트 알림 대신 메시지 상자를 띄워요:

"command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude has finished', 'Claude Code')\""

메시지 상자가 terminal 창 뒤에 열릴 수 있으니 먼저 PowerShell에서 명령을 테스트해 보세요. WSL에서는 Windows interop을 통해 powershell.exe를 실행할 수 있어야 해요. 다른 방법은 Windows 가이드에서 확인하세요.

05동작 확인하기

1. Claude Code에서 /hooks를 입력하세요. Stop과 Notification 아래에 hook이 표시되어야 해요.
2. Claude에게 간단한 질문을 해 보세요. 답변이 끝나면 Stop 알림이 떠야 해요.
3. 권한이 필요한 작업을 요청한 뒤 다른 창으로 전환해서 기다려 보세요. 약 6초 후에 permission_prompt 알림이 와요.

settings.json 변경 사항은 보통 바로 반영돼요. /hooks에 hook이 보이지 않으면 파일이 올바른 JSON인지(끝에 붙은 쉼표나 주석이 없는지) 확인하세요. claude --debug로 Claude Code를 실행하면 각 hook이 무엇을 했는지 볼 수 있어요. 더 많은 해결 방법은 문제 해결 체크리스트에 있어요.

06휴대폰으로 알림 받기

데스크톱 알림은 자리에 있을 때만 쓸모가 있어요. 자리를 비우면 다른 곳에서 알림을 받아야 하죠. 흔히 쓰는 방법은 세 가지예요:

• 직접 운영하는 push 서비스: ntfy 같은 서비스를 같은 hook에서 curl로 호출하는 방식이에요. 저렴하고 유연해요. ntfy 가이드를 참고하세요.
• 채팅 webhook: Telegram, Slack, Discord용이에요. 이미 채팅 앱을 늘 쓰고 있다면 좋은 선택이에요. 채팅 webhook 가이드를 참고하세요.
• Claude Code Notifier: hook 설정을 대신 해 주고 휴대폰에서 바로 응답할 수 있게 해 줘요.

알림만 받으면 된다면 직접 구성하는 방법으로도 충분해요. 다만 단방향이라는 한계가 있어요. Claude가 기다리고 있다는 건 알 수 있지만, 무언가를 승인하려면 결국 키보드 앞으로 돌아가야 해요.

Claude Code Notifier는 Anthropic이 만든 것이 아닌 독립 도구로, 두 부분으로 구성돼요. Mac, Windows, Linux용 무료 커맨드라인 도구인 ccn과 iPhone 및 Android 앱이에요. 한 줄로 설치할 수 있어요:

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

Windows에서는 PowerShell에서 irm https://claudecodenotifier.com/install.ps1 | iex를 실행하세요(Windows 지원은 베타예요). Homebrew, npx @touchtap/ccn, Claude Code 플러그인 등 다른 방법은 ccn 페이지에 있어요.

설치하면 각각 ccn hook을 실행하는 hook 항목 7개가 추가되고, settings.json의 나머지 내용은 그대로 유지되며, 같은 위치에 백업이 한 번 저장돼요. 휴대폰이 없어도 ccn은 Claude가 작업을 마치거나, 권한이 필요하거나, 질문할 때 컴퓨터에 데스크톱 알림을 띄워 줘요. 이 기능은 무료이고 네트워크 없이도 동작해요.

ccn pair로 휴대폰을 페어링하면 다음 기능도 쓸 수 있어요:

• 턴이 끝나는 즉시 "Claude has finished" push 알림
• 한 번만 허용, 세션 동안 허용, 거부 중에서 선택할 수 있는 권한 요청
• 휴대폰에서 답할 수 있는 Claude의 객관식 질문
• Claude가 작업을 마치자마자 다음 지시를 보낼 수 있는 후속 입력창

최근 30초 안에 입력한 적이 있다면 휴대폰 응답을 기다리지 않고 terminal에서 평소처럼 물어봐요. 앱은 구독 또는 평생 이용권 구매가 필요해요. 가격을 확인하세요. 설정 방법은 휴대폰 페어링하기에서 단계별로 안내해요.

07FAQ