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

서론

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

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

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

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

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

Claude Code의 Hooks를 사용하면 라이프사이클 이벤트에 임의의 명령어를 연결할 수 있습니다.
~/.claude/settings.json에 Stop / PreToolUse(AskUserQuestion) 등을 설정합니다.
/PermissionRequest를 설정하면, 작업 완료·질문·권한 요청을 소리로 구분하여 들을 수 있습니다. macOS라면 afplay와 /System/Library/Sounds/에 있는 표준 사운드만으로도 충분합니다.

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