Claude Code: Hooks 간단 실습

개요

Antropic의 Claude Code가 hooks(공식문서) 기능을 발표했다. 코드 생성 작업을 마치면 포맷을 검토한다거나, 작업의 로그를 기록하는 등 활용법은 무궁무진하겠다. 여기서는 매우 간단한 기능 적용으로 hooks 에 대한 감을 잡아보자.

기능 간단 소개

• Notifications: Claude Code가 입력을 기다리거나 무언가를 실행하기 위한 권한을 요청할 때 어떤 방식으로 알림을 받을지 사용자 지정
• Automatic formatting: 파일을 수정할 때마다 .ts 파일에는 prettier, .go 파일에는 gofmt 등을 자동으로 실행.
• Logging: 모든 실행된 명령을 추적하고 집계하여 컴플라이언스(규정 준수)나 디버깅에 활용.
• Feedback Claude Code가 코드베이스 규칙을 따르지 않는 코드를 생성할 경우 자동으로 피드백을 제공.
• Custom permissions: 운영 중인 파일이나 민감한 디렉토리에 대한 수정 작업을 차단.

Claude Code에 알림음 추가하기

목표

Claude Code를 사용하다보면 중간에 사람의 허가를 요청하며 대기하는 경우가 있다. 열심히 일하고 있겠거니 하는데 이러고 있으면 속상하다. 여기에 알림음을 넣어주는게 목표다. Notification hook 이벤트이다. Cursor 설정에는 응답 완료시 알림음이 울리도록 하는데 Claude Code의 응답이 완료되는 경우에도 알림음이 울리도록 하겠다. Stop hook 이벤트이다.

알림음 실행하는 방법

hook 이벤트가 발생할 때 어떻게 소리를 실행할 것인지를 먼저 알아보자. 여기서는 MacBook 에서의 방법만을 다루지만 “터미널에서 소리가 나는 명령을 실행한다”는 개념만 이해하면 다른 환경에서도 방법을 찾는게 어렵지 않을 것이다.

afplay

afplay는 macOS 터미널에서 mp3·wav 등 오디오 파일을 즉시 재생하는 기본 CLI 도구이다. 그리고 /System/Library/Sounds/ 디렉터리에는 몇몇 효과음 파일들이 있다. 다음과 같이 터미널에서 실행하면 효과음이 재생될 것이다.

afplay /System/Library/Sounds/Tink.aiff

say

say는 macOS 터미널에서 지정한 텍스트를 시스템 TTS 음성으로 읽어주거나 -o 옵션으로 오디오 파일로 저장할 수 있는 기본 CLI 도구이다. say 뒤에 원하는 영어 단어나 문장을 입력하면 문장을 말해준다.

say completed

한국어도 가능하다.

say -v Yuna "작업 완료"

설정하기

Claude Code에서의 설정방법은 다음 동영상을 참고하자.

• Notification 이벤트 발생시에 afplay /System/Library/Sounds/Funk.aiff 명령을 실행하고,
• Stop 이벤트 발생시에 afplay /System/Library/Sounds/Tink.aiff 명령을 실행하는게 전부이다.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

hook 을 저장할 위치는 user, project, project local(commit 되지 않는다)로 설정 할 수 있다. user로 설정하여 이 컴퓨터에서 Cluade Code 사용시에는 모든 경우에 적용되도록 하였다.

 

이렇게 설정하고 나면 ~/.claude/settings.json 에 다음과 같이 설정이 되어있다. 필요하다면 이 파일을 직접 수정해도 된다. 수정 이후에 Claude Code를 재시작하면 설정이 반영된 것을 확인할 수 있다.

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Tink.aiff"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Funk.aiff"
          }
        ]
      }
    ]
  }
}

결과

Notification은 웹사이트 URL을 주면서 확인 요청을 하거나, git commit 등의 명령을 주는 방법으로 확인이 가능하다. Notification은 사람의 행동을 몇 초 기다린 다음에 알림음을 울리기에 조금 기다려주자.

Stop은 어떤 명령이든 완료시에 바로 알림이 뜨니 확인이 쉬울 것이다.