Claude Code의 Hooks를 사용하여 작업 완료와 대기 상태를 소리와 알림으로 알리기 + 응용

Claude Code에 작업을 의뢰하면 시간이 다소 걸리기 때문에, 대기 시간 동안 다른 작업을 하고 싶어집니다.

그럴 때 작업이 완료되었을 때 알림이 울려준다면 타임로스(Time loss)를 줄일 수 있어 도움이 됩니다.

Claude Code의 Hooks라는 기능을 사용하여 Claude Code가 "작 작업을 완료했을 때", "작업 도중에 사용자에게 확인을 요청하며 정지해 있을 때" 소리를 내는 방법을 소개합니다.

또한, 응용 단계로 VSCode나 터미널 등 여러 애플리케이션 상에서 Claude Code를 실행했을 때 어떤 애플리케이션으로부터 온 알림인지 알 수 있도록 하는 방법에 대해서도 기록하겠습니다.

공식 문서에서 인용하면 다음과 같이 정의되어 있습니다.

후크(Hook)는 Claude Code의 라이프사이클 내 특정 시점에서 자동으로 실행되는 사용자 정의 셸 명령(Shell command), HTTP 엔드포인트 또는 LLM 프롬프트입니다.

대략적으로 말하자면, Hooks는 특정 이벤트에서 임의의 명령을 실행할 수 있는 메커니즘입니다.

이번에 사용하는 것은 그중에서도 두 가지 이벤트인 Stop(응답 완료 시)과 Notification(사용자의 입력/허가 대기 시)입니다.

실제로 사용 중인 ~/.claude/settings.json의 hooks 섹션은 다음과 같습니다.

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

음성은 macOS 표준으로 탑재되어 있는 음성을 유용합니다. (/System/Library/Sounds/*.aiff)

음성은 종류에 따라 구분함으로써, 작업이 끝난 것인지 확인하고 싶은 것이 있는 것인지를 소리만으로 판단할 수 있습니다.

• Stop: afplay /System/Library/Sounds/Glass.aiff 소리 + osascript로 알림 센터에 "작업이 완료되었습니다"라고 표시
• Notification: afplay /System/Library/Sounds/Funk.aiff 소리 + osascript로 알림 센터에 "확인이 필요합니다"라고 표시

osascript의 display notification을 사용하여 Mac의 알림 센터에도 나타나도록 하고 있습니다.

여러 애플리케이션에서 Claude Code를 실행하면 어떤 애플리케이션으로부터 온 알림인지 알 수 없게 되기 쉽습니다.

그래서 응용으로서, 어떤 애플리케이션으로부터 온 알림인지 알 수 있도록 알림을 클릭했을 때 해당 알림의 출처 애플리케이션으로 전환할 수 있도록 만들고자 합니다.

저는 VSCode의 확장 기능인 Claude Code, VSCode 상의 터미널에서 구동 중인 Claude Code, 터미널 앱 Warp, macOS 표준 터미널을 사용하는 경우가 있으므로, 이번에는 해당 환경에서의 샘플을 소개합니다.

어떤 Claude Code인지 구별하기 위해서는 후크(Hook)의 명령에 표준 입력(Standard input)으로 전달되는 JSON을 사용합니다. 여기에는 트리거 시점의 작업 디렉토리 cwd와 세션 ID session_id가 포함되어 있으며, jq로 추출할 수 있습니다.

작업 디렉토리의 끝(basename)을 프로젝트 이름으로 하여 알림 제목에 넣으면, 어떤 Claude Code가 울렸는지 한눈에 알 수 있습니다.

INPUT="$(cat)"
CWD="$(printf '%s' "$INPUT" | jq -r '.cwd // empty')"
PROJECT="$(basename "${CWD:-Claude}")" # 예: blog
...

(macOS 표준 터미널 · Downloads 폴더에서 실행)

settings.json에 명령을 직접 작성하면 읽기 어려워지므로, ~/.claude/hooks/notify.sh와 같은 외부 스크립트로 분리하여 호출하는 방식으로 해둡니다.

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

알림을 클릭하여 해당 윈도우로 전환하고 싶지만, 여기서 한 가지 벽이 있습니다. 표준 osascript -e 'display notification ...'은 알림을 띄울 수는 있지만, 클릭했을 때의 동작을 지정할 수 없습니다.

그래서 terminal-notifier를 사용합니다. -execute 옵션에 클릭되었을 때 실행할 명령을 전달할 수 있습니다.

brew install terminal-notifier

VSCode 확장 기능이든 통합 터미널(Integrated Terminal)이든, 이동 대상은 "해당 워크스페이스를 열고 있는 VSCode 창"입니다. code "$CWD"를 실행하면, 해당 작업 디렉터리를 열고 있는 기존 창이 전면으로 나옵니다(열려 있지 않다면 새로 엽니다).

# 주의: -execute는 최소 PATH의 쉘에서 실행되므로, code는 절대 경로로 지정해야 합니다
CODE_BIN="$(command -v code)"
terminal-notifier \
...

-group에 동일한 값을 전달하면, 동일한 프로젝트의 이전 알림이 새로운 알림으로 교체되어 알림 센터가 지저분해지는 것을 방지할 수 있습니다.

Warp는 이 방식과는 별개로, AppleScript를 지원하지 않는 대신 네이티브 알림 메커니즘을 가지고 있습니다. claude-code-warp 플러그인을 설치해 두면 Warp 탭에 연결된 알림이 나타나며, 클릭 시 해당 탭으로 이동합니다. Warp를 사용하는 경우에는 이 방식에 맡기는 것이 가장 심플합니다.

• Stop / Notification에 소리 + 알림을 할당하는 것만으로도 대기 시간의 스트레스가 급격히 줄어듭니다.
• 응용 사례로
  cwd로 판별 + terminal-notifier를 통해 클릭 시 이동까지 구현할 수 있었습니다.