Claude Code 후크(Hook) 설정 정리 — 음성 읽어주기 및 macOS/Windows 알림 자동화

Claude Code로 긴 작업을 실행하면서 다른 작업을 하다 보면, "정신을 차려보니 이미 완료되어 있었다"거나 "권한 확인 다이얼로그에서 멈춰 있었다"는 상황이 발생하기 쉽습니다.

이 기사에서는 Claude Code의 hooks 기능을 사용하여, 작업 완료 시 및 권한 확인 시 macOS / Windows의 네이티브 알림과 음성 읽어주기를 자동으로 출력하는 설정 방법을 정리합니다.

• Claude Code에는 Stop(완료 시)과 PermissionRequest(권한 확인 시) 후크가 있음
• macOS: osascript로 알림, /usr/bin/say -v Kyoko로 일본어 음성 읽어주기
• Windows: PowerShell의 SpeechSynthesizer로 음성 읽어주기, BurntToast로 토스트 알림
• async: true를 추가하여 본래의 처리를 블록(Block)하지 않음
• 설정 파일은 ~/.claude/settings.json(글로벌 설정)

Claude Code의 hooks는 특정 타이밍에 셸 명령(Shell Command)을 자동으로 실행할 수 있는 메커니즘입니다.

주요 후크 종류:

후크 이름	발생 타이밍
Stop	Claude가 답변/작업을 완료한 직후
PermissionRequest	허가 리스트에 없는 도구 실행 전 (권한 다이얼로그가 나오기 직전)
Notification	자리를 비웠을 때의 대기 알림

~/.claude/settings.json (글로벌 설정)

다음 내용을 settings.json의 hooks 키에 추가합니다.

"hooks": {
"Stop": [
{
...

• osascript: macOS 네이티브 알림을 표시하는 명령
• /usr/bin/say -v Kyoko: macOS의 일본어 음성(Kyoko = 일본어 여성 보이스)으로 읽어주기
• 2>/dev/null: 에러 출력을 버리고 불필요한 로그를 남기지 않음
• async: true: 후크를 비동기(Asynchronous)로 실행하여 Claude 본래의 처리를 블록하지 않음 (중요)

# /hooks 명령으로 확인 및 반영
/hooks
# 또는 Claude Code를 재시작

Windows에서는 osascript나 say 명령을 사용할 수 없으므로, PowerShell로 동등한 기능을 구현합니다.

PowerShell에 표준 탑재된 System.Speech.Synthesis.SpeechSynthesizer를 사용합니다.

전제 조건: 일본어 음성 팩이 Windows에 설치되어 있을 것
(설정 → 시간 및 언어 → 음성 인식 → 음성 관리 → 음성 추가 → "일본어" 추가)

"hooks": {
"Stop": [
{
...

BurntToast를 사용하면 macOS의 osascript와 유사한 토스트 알림을 띄울 수 있습니다.

먼저 PowerShell을 관리자 권한으로 열고, 모듈을 설치합니다.

Install-Module -Name BurntToast -Force

settings.json 설정:

"hooks": {
"Stop": [
{
...

기능	macOS	Windows
알림 표시	osascript	BurntToast (설치 필요)
음성 읽어주기	/usr/bin/say -v Kyoko	System.Speech.SpeechSynthesizer
일본어 대응	기본적으로 이용 가능	일본어 음성 팩 추가 필요

환경	동작
Claude Code CLI (터미널)	✅ 유효
...

CLI, 데스크톱, 원격 조작 중 어느 것이든 동작하므로, 평소 사용 방식에 상관없이 설정해 둘 가치가 있습니다.

참고로, 브라우저 버전(claude.ai)에 알림을 띄우고 싶은 경우에는 브라우저의 알림 설정에서 허용이 필요합니다.

• claude.ai 를 브라우저에서 열기

• 주소창 왼쪽의 🔒 아이콘 → 「알림」 → 「허용」

• Safari의 경우: 설정 → 웹 사이트 → 알림 → claude.ai 를 「허용」

• Claude.ai의 설정 화면에서 알림 항목을 ON으로 설정

※ 브라우저 버전에서는 음성 읽어주기 등의 커스텀 알림을 설정할 수 없습니다.

사용 가능한 보이스(Voice) 목록은 다음 명령어로 확인할 수 있습니다.

say -v ?

일본어 보이스 예시: Kyoko (여성), Otoya (남성)

-r 옵션으로 분당 단어 수(wpm)를 지정합니다. 기본값은 약 175입니다.

say -v Kyoko -r 120 '作業が完了したよ' # 느리게
say -v Kyoko -r 175 '作業が完了したよ' # 표준
say -v Kyoko -r 250 '作業が完了したよ' # 빠르게

settings.json의 명령에 포함할 때는 -r을 추가하기만 하면 됩니다.

"command": "osascript -e 'display notification \"作業が完了したよ\" with title \"Claude Code\"' 2>/dev/null; /usr/bin/say -v Kyoko -r 120 '作業が完了したよ' 2>/dev/null"

macOS 표준 사운드를 미리 들어보고 마음에 드는 것을 찾기:

afplay /System/Library/Sounds/Hero.aiff

사용 가능한 사운드 목록 (/System/Library/Sounds/ 내):

Basso, Blow, Bottle, Frog, Funk, Glass, Hero, Morse,
Ping, Pop, Purr, Sosumi, Submarine, Tink

알림음을 울리고 싶다면, say 대신 afplay를 사용하거나 조합할 수 있습니다.

Add-Type -AssemblyName System.speech
(New-Object System.Speech.Synthesis.SpeechSynthesizer).GetInstalledVoices() | ForEach-Object { $_.VoiceInfo.Name }

일본어 보이스 예시: Microsoft Haruka Desktop (여성), Microsoft Ichiro Desktop (남성)

특정 보이스를 지정하여 읽어주는 경우, 다음과 같이 SelectVoice를 사용합니다.

Add-Type -AssemblyName System.speech
$speak = New-Object System.Speech.Synthesis.SpeechSynthesizer
$speak.SelectVoice('Microsoft Haruka Desktop')
...

settings.json의 명령에 포함할 경우:

"command": "powershell -ExecutionPolicy Bypass -Command \"Add-Type -AssemblyName System.speech; $s = New-Object System.Speech.Synthesis.SpeechSynthesizer; $s.SelectVoice('Microsoft Haruka Desktop'); $s.Speak('作業が完了したよ')\""

Rate 속성으로 속도를 조절할 수 있습니다 (-10: 가장 느림 ~ 10: 가장 빠름, 기본값: 0).

$speak.Rate = -2 # 조금 느리게

-Sound 옵션으로 알림음을 지정할 수 있습니다.

New-BurntToastNotification -Text 'Claude Code', '作業が完了したよ' -Sound IM

사용 가능한 알림음: Default, IM, Mail, Reminder, SMS, Alarm, Alarm2 등

• Claude Code의 Stop 및 PermissionRequest

후크(Hook)를 통해 완료 알림 및 권한 확인 알림을 자동화할 수 있습니다.

macOS:
osascript와 say -v Kyoko를 조합하면 추가 설치 없이 즉시 사용할 수 있습니다.

Windows:
SpeechSynthesizer(의존성 없음) 또는 BurntToast(토스트 알림 포함)를 사용하여 동일한 기능을 구현할 수 있습니다.

async: true를 잊지 않고 추가하면 Claude의 처리를 차단하지 않는 안전한 설정이 됩니다.

Claude Code를 "실행해 두면서 다른 작업을 하는" 스타일로 활용하고 싶다면 꼭 도입해 보세요.