Claude Code 알림: 기다리는 중인지 끝났는지 소리로 구분하기

"막혀 있는 세션과 끝난 세션이 똑같아 보여서 엉뚱한 세션부터 열게 됩니다." Claude Code 기능 요청에 올라온 이 한 줄이 문제를 요약합니다. 각각에 다른 신호를 받는 방법을 소개합니다.

작성: Aslan, Pet Island 팀 · 업데이트: 2026년 10월 26일 · 읽는 데 4분

핵심 요약

Claude Code는 사용자가 자리를 비운 사이 작업을 끝내거나 권한을 기다릴 때 이미 알림을 발생시키지만, 기본적으로 데스크톱 알림으로 표시하는 것은 Ghostty, Kitty, iTerm2뿐입니다. 다른 곳에서는 "preferredNotifChannel": "terminal_bell"을 설정하세요. 두 가지 다른 소리를 원한다면 "내가 필요함"에는 permission_prompt matcher를 사용한 Notification 훅을, "완료"에는 Stop 훅을 사용하세요.

Claude Code가 기본으로 하는 일

Claude가 작업을 끝내거나 권한 프롬프트 때문에 멈췄는데 사용자가 터미널을 떠나 있는 것으로 보이면 알림 이벤트를 발생시킵니다. 기본적으로 이 이벤트가 데스크톱 알림으로 표시되는 곳은 Ghostty, Kitty, iTerm2뿐입니다. Windows Terminal, VS Code 터미널, Warp 등에서는 직접 설정하지 않으면 눈에 보이는 일이 일어나지 않습니다.

가장 간단한 해결책은 터미널 벨입니다.

~/.claude/settings.json복사

{

"preferredNotifChannel": "terminal_bell"

}

벨이 무엇을 할지는 터미널에 달려 있습니다. Windows Terminal에서 bellStyle 설정은 audible(기본값), window, taskbar, all, none 중 하나입니다. all로 설정하면 Windows Terminal은 소리를 내고 작업 표시줄 아이콘을 깜박입니다.

iTerm2: Settings → Profiles → Terminal → "Notification Center Alerts"를 선택한 다음, Filter Alerts에서 "Send escape sequence-generated alerts"를 켭니다.
tmux: ~/.tmux.conf에 set -g allow-passthrough on을 추가하세요. 그렇지 않으면 알림이 바깥 터미널에 전달되지 않습니다.
SSH 사용 시: 데스크톱 알림이 로컬 컴퓨터로 전달되므로 원격 세션에서도 알림을 받을 수 있습니다.

시스템 알림 기능 요청(#26581, 추천 34개)은 이미 제공되는 기능이라며 바로 이 기본 알림을 가리키고 종료되었습니다. "대기 중"과 "완료"에 다른 신호를 달라는 요청(#94373)은 아직 열려 있습니다. 여기서 훅이 필요해집니다.

두 가지 이벤트: Notification과 Stop

Notification 이벤트는 Claude Code가 알림을 보낼 때 발생합니다. matcher는 알림 유형입니다. 신경 써야 할 두 가지는 permission_prompt(Claude가 도구 사용 승인을 요청했고 프롬프트가 약 6초간 대기함)와 idle_prompt(Claude가 약 60초 전에 응답을 마쳤고 그 후 입력이 없음)입니다.
Stop 이벤트는 Claude가 응답을 마칠 때마다 발생합니다. 사용자가 중단하면 발생하지 않으며, API 오류에서는 대신 StopFailure가 발생합니다.

훅은 기본 알림을 대체하지 않고 함께 실행되므로 둘 다 유지할 수 있습니다.

Windows: 두 가지 다른 소리

Windows에서 훅은 Git Bash에서 실행되며, Git Bash가 설치되어 있지 않으면 PowerShell에서 실행됩니다. "shell": "powershell"을 설정하면 추측할 필요가 없습니다. 다음 구성은 Claude에 권한이 필요할 때 높은 비프음을 두 번, 끝났을 때 낮은 비프음을 한 번 냅니다.

%USERPROFILE%\.claude\settings.json복사

{

"hooks": {

"Notification": [

{

"matcher": "permission_prompt",

"hooks": [

{ "type": "command", "shell": "powershell",

"command": "[Console]::Beep(1320, 150); [Console]::Beep(1320, 150)" }

]

}

"Stop": [

{

"hooks": [

{ "type": "command", "shell": "powershell",

"command": "[Console]::Beep(660, 300)" }

]

}

]

}

Console.Beep은 헤르츠 단위의 주파수와 밀리초 단위의 지속 시간을 받으며, 비프음이 끝날 때까지 기다립니다. Anthropic의 훅 가이드에는 System.Windows.Forms로 메시지 상자를 여는 Windows 예시도 있는데, 문서 스스로 이것이 알림이 아니라 대화 상자이며 터미널 뒤에 열릴 수 있다고 적고 있습니다.

macOS 및 Linux

Anthropic 문서는 macOS에서 afplay를 사용합니다.

~/.claude/settings.json복사

{

"hooks": {

"Notification": [

{

"matcher": "permission_prompt",

"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]

}

"Stop": [

{

"hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Pop.aiff" }]

}

]

}

눈에 보이는 알림을 원한다면 macOS에서는 osascript -e 'display notification "Claude needs you" with title "Claude Code"', Linux에서는 notify-send "Claude Code" "Claude needs you"를 사용하세요.

저녁 시간을 아껴 주는 세부 사항

Stop은 자주 발생합니다. 전체 작업이 끝났을 때만이 아니라 Claude가 응답을 마칠 때마다 발생합니다. 너무 잦다면 대신 idle_prompt 알림을 사용하세요. 약 1분을 기다리고, 그동안 입력하지 않았을 때만 발생합니다.
필요하면 이벤트를 읽으세요. Notification 입력에는 message, title, notification_type이 포함되어 있어 스크립트가 실제 요청 내용을 보여 줄 수 있습니다.
Agent view. claude agents로 백그라운드 세션을 실행하면, 세션이 입력을 필요로 하기 시작하거나 완료되거나 실패할 때 같은 preferredNotifChannel로 알려 주며, agent_needs_input 또는 agent_completed 유형으로 Notification 훅을 발생시킵니다.
터미널 상태. OSC 7501 상태 프로토콜을 구현한 터미널은 각 Claude Code 세션이 작업 중인지, 대기 중인지, 완료되었는지 표시할 수 있습니다. Claude Code v2.1.295 이상은 이를 자동으로 보고합니다.
Windows에서 훅이 실행되지 않나요? Windows에서 Claude Code 훅이 작동하지 않을 때를 참고하세요. 원인은 거의 항상 셸입니다.

어느 세션인지 보고 바로 응답하기

소리는 무언가 일어났다는 것만 알려 줄 뿐, 세 개의 터미널 중 어디서 왔는지, Claude가 무엇을 실행하려는지는 알려 주지 않습니다. Pet Island는 모든 Claude Code 세션에 화면 상단의 작은 아일랜드 자리를 주고 작업 중, 응답 대기, 완료 상태를 보여 줍니다. 권한 요청은 명령이나 diff와 함께 도착하며 그 자리에서 허용하거나 거부할 수 있고, 질문과 계획도 같은 방식으로 처리됩니다. 자세히 보고 싶을 때는 클릭 한 번으로 해당 터미널로 이동합니다.

자주 묻는 질문

Claude Code에 알림 기능이 있나요?

네. 자리를 비운 사이 작업을 끝내거나 권한을 기다릴 때 알림을 발생시킵니다. Ghostty, Kitty, iTerm2는 기본적으로 데스크톱 알림으로 표시하며, 다른 터미널에서는 preferredNotifChannel을 "terminal_bell"로 설정하거나 Notification 훅을 추가하세요.

Claude Code가 끝났을 때 소리를 듣으려면 어떻게 하나요?

소리를 재생하는 Stop 훅을 추가하세요. 예를 들어 macOS에서는 afplay, Windows에서는 PowerShell의 [Console]::Beep을 사용합니다.

"권한 필요"와 "완료"를 어떻게 구분하나요?

permission_prompt matcher를 사용한 Notification 훅으로 한 가지 소리를, Stop 훅으로 다른 소리를 내세요.

Windows Terminal이나 VS Code에서 알림이 오지 않는 이유는 무엇인가요?

Claude Code는 기본적으로 Ghostty, Kitty, iTerm2에서만 데스크톱 알림을 보냅니다. preferredNotifChannel을 "terminal_bell"로 설정하거나 훅을 사용하세요.

tmux 안에서도 알림이 작동하나요?

네, ~/.tmux.conf에 set -g allow-passthrough on을 추가하면 작동합니다.

출처

이 페이지의 모든 설정과 동작은 2026년 10월 26일에 아래 페이지와 대조해 확인했습니다. 에이전트는 빠르게 바뀌므로, 내용이 더 이상 맞지 않으면 공식 페이지를 따르세요.

더 읽어보기

Windows