Claude Code 작업 완료를 소리로 알리는 Hooks 설정 방법

서론

Claude Code의 작업 완료, 질문, 권한 요청을 Hooks를 통해 macOS의 표준 사운드로 구분하여 들을 수 있도록 설정하는 방법을 정리합니다.

Hooks란

Hooks는 Claude Code 측의 이벤트에 대해 사용자가 정의한 명령어를 후킹(Hook)시키는 메커니즘입니다. 대표적인 이벤트는 다음과 같습니다.

이벤트	발생 타이밍
Stop	어시스턴트가 응답을 마치고 사용자 입력을 기다릴 때
PreToolUse	도구(Tool)를 실행하기 직전 (matcher를 통해 도구 이름을 좁힐 수 있음)
PostToolUse	도구 실행이 끝난 직후
PermissionRequest	권한 허용을 요청하는 다이얼로그가 나타날 때
Notification	알림이 발생했을 때

설정은 ~/.claude/settings.json (사용자 전체) 또는 .claude/settings.json (프로젝트 단위)에 작성합니다.

설정 방법

macOS의 afplay 명령어를 사용하여 /System/Library/Sounds/ 하위의 표준 사운드를 재생합니다. ~/.claude/settings.json에 다음과 같이 추가합니다.

{
  "hooks": {
    "Stop": [
      ...
    ]
  }
}

포인트는 다음과 같습니다.

• Stop: 작업이 일단락되는 타이밍입니다. 가장 자주 울리는 소리이므로 자신에게 거슬리지 않는 것을 선택하세요.
• PreToolUse + matcher: "AskUserQuestion": AskUserQuestion 도구가 실행되기 직전에 울립니다. 즉, "Claude가 질문을 했을 때"의 알림입니다.
• PermissionRequest: 허용 다이얼로그가 나타날 때입니다. 이를 놓치면 작업이 중단되므로 가장 눈에 띄는 소리로 설정해 두는 것이 안전합니다.

끝에 붙는 2>/dev/null || true는 사운드 파일을 찾을 수 없는 환경(예: Linux)에서 후킹이 실패하더라도 Claude Code 측에 영향을 주지 않기 위한 보험입니다.

소리 선택 방법

/System/Library/Sounds/에는 다음과 같은 .aiff 파일들이 준비되어 있습니다.

$ ls /System/Library/Sounds/
Basso.aiff Frog.aiff Hero.aiff Pop.aiff Submarine.aiff
Blow.aiff Funk.aiff Morse.aiff Purr.aiff Tink.aiff
...

사전에 미리 들어보고 할당하면 실수를 줄일 수 있습니다.

afplay /System/Library/Sounds/Funk.aiff
afplay /System/Library/Sounds/Glass.aiff
afplay /System/Library/Sounds/Submarine.aiff

저의 구분 기준은 다음과 같습니다.

이벤트	소리	이유
Stop	Funk	짧고 가볍다. 여러 번 울려도 피로감이 없다
AskUserQuestion	Glass	맑은 소리로 "잠시 물어볼 것이 있다"는 느낌을 준다
PermissionRequest	Submarine	저음이라 눈에 띈다. 놓치고 싶지 않은 알림에 적합하다

설정 후 동작 확인

설정을 반영하려면 Claude Code를 재시작합니다. 그 후 적당한 태스크를 요청하여 다음 세 가지를 확인하면 성공입니다.

• 응답이 끝나는 타이밍에 Funk가 울리는지
• AskUserQuestion을 사용한 질문이 오는 타이밍에 Glass가 울리는지
• 파일 편집 등 권한이 필요한 조작에서 Submarine이 울리는지

소리가 제대로 울리지 않을 때는 터미널에서 직접 afplay가 작동하는지 확인해 보세요. OS의 사운드 출력 대상(AirPods가 별도 장치로 잡혀 있는 등)이 원인인 경우도 많습니다.

요약

• Claude Code의 Hooks를 사용하면 라이프사이클 이벤트에 임의의 명령어를 연결할 수 있습니다.

• ~/.claude/settings.json에 Stop / PreToolUse(AskUserQuestion) 등을 설정합니다.

• /PermissionRequest를 설정하면, 작업 완료·질문·권한 요청을 소리로 구분하여 들을 수 있습니다. macOS라면 afplay와 /System/Library/Sounds/에 있는 표준 사운드만으로도 충분합니다.

"Claude Code에게 맡긴 작업이 끝날 때마다 터미널을 확인하러 가는" 습관이 사라지는 것만으로도 체감 생산성은 상당히 높아집니다. 꼭 한번 시도해 보세요.