Stop 훅으로 완료 알림·로그 자동화

Stop 훅은 Claude가 태스크를 완료하고 응답을 끝냈을 때 자동으로 실행되는 훅입니다. 대규모 리팩터링이나 테스트처럼 오래 걸리는 작업을 맡겨 두고 화면을 계속 지켜보는 것은 비효율적이고, 다른 일을 하다 보면 완료를 놓치기도 합니다. Stop 훅으로 알림음이나 데스크톱 알림을 걸어 두면 안심하고 다른 작업에 집중할 수 있습니다. SessionStart 훅에서 쓴 ~/Desktop/hooks-test 디렉터리를 이어서 사용합니다.

핵심 요약

• Stop 훅은 Claude의 응답이 완료될 때 발화합니다.
• 완료 알림, 로그 기록, 후처리를 자동화할 수 있습니다.
• settings.json 또는 settings.local.json에 설정합니다.
• macOS에서는 afplay나 osascript로 알림을 구현할 수 있습니다.

Stop 훅은 언제 발화하나

Stop 훅은 응답이 끝날 때마다 발화합니다. 간단한 질문에 대한 답변에도 발화하므로, 알림음을 걸어 두면 너무 자주 울려 번거로워질 수 있습니다. 실무에서는 장시간 태스크를 맡길 때만 활성화하는 식으로 가려 쓰는 편이 좋습니다. 알림처럼 개인 환경에 묶인 설정은 .claude/settings.local.json에 두면 팀 공유 설정과 섞이지 않습니다. 훅 전체의 종류는 훅 개요를 참고하세요.

기본 설정 형식

Stop 훅은 settings.json에 다음 형식으로 적습니다. 설정 파일의 기본 구조는 Hooks 설정 방법에서 다뤘습니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "실행하고 싶은 명령"
          }
        ]
      }
    ]
  }
}

• matcher: Stop 훅에서는 생략합니다(매처 개념이 없기 때문).
• type: "command"를 지정해 셸 명령을 실행합니다.
• command: 실행할 명령을 적습니다.

간단한 예로 동작 확인하기

응답이 끝날 때마다 로그 파일에 한 줄을 남기는 예로 동작을 확인합니다.

1. 테스트용 디렉터리로 이동합니다(없으면 만듭니다).

mkdir -p ~/Desktop/hooks-test/.claude
cd ~/Desktop/hooks-test

1. .claude/settings.json에 아래 설정을 추가합니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"응답 완료: $(date)\" >> ~/Desktop/hooks-test/stop.log"
          }
        ]
      }
    ]
  }
}

1. 같은 디렉터리에서 Claude Code를 실행하고 "안녕하세요" 같은 간단한 질문을 던집니다.

cd ~/Desktop/hooks-test
claude

1. 응답이 끝난 뒤 로그를 확인합니다.

cat ~/Desktop/hooks-test/stop.log
# 응답 완료: Mon 29 Dec 2025 15:30:45 KST

이렇게 먼저 로그 출력으로 Stop 훅의 동작을 확인한 뒤 실전 설정으로 넘어가세요.

완료 시 알림음 울리기

macOS에서는 afplay 명령으로 시스템 사운드를 재생할 수 있습니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          }
        ]
      }
    ]
  }
}

이 설정으로 응답이 끝날 때마다 'Glass' 사운드가 울립니다. macOS에는 여러 시스템 사운드가 있으니 취향에 맞게 바꾸면 됩니다.

• /System/Library/Sounds/Glass.aiff — 투명감 있는 소리
• /System/Library/Sounds/Ping.aiff — 짧은 핑 소리
• /System/Library/Sounds/Submarine.aiff — 묵직한 소리
• /System/Library/Sounds/Hero.aiff — 성취감 있는 소리

Windows에서는 PowerShell로 알림음을 울릴 수 있다고 알려져 있습니다. 검증된 설정은 아니므로 참고용으로만 보세요.

{
  "type": "command",
  "command": "powershell -c \"[System.Media.SystemSounds]::Asterisk.Play()\""
}

데스크톱 알림 표시하기

소리뿐 아니라 시각적인 알림도 원한다면 osascript 명령을 씁니다. macOS에서 AppleScript를 실행하는 표준 명령입니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"태스크 완료\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

이 설정으로 macOS 알림 센터에 "Claude Code"라는 제목으로 "태스크 완료" 메시지가 표시됩니다.

알림음과 데스크톱 알림을 함께 쓰려면 hooks 배열에 핸들러를 둘 다 추가합니다. 같은 배열 안의 명령은 병렬로 실행되고, 모든 명령이 끝난 결과가 합쳐집니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "afplay /System/Library/Sounds/Glass.aiff"
          },
          {
            "type": "command",
            "command": "osascript -e 'display notification \"태스크 완료\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Notification·SubagentStop 과는 무엇이 다른가

Stop 훅과 비슷해 보이는 훅이 두 가지 있습니다.

용도가 다르므로 일반적인 태스크 완료 시 처리에는 Stop 훅을 씁니다. 서브에이전트 완료 시 처리는 SubagentStop 훅에서 따로 다룹니다.

정리

• Stop 훅은 Claude의 응답이 끝날 때마다 발화하며, matcher 없이 type과 command만 적습니다.
• 먼저 로그 출력으로 동작을 확인한 뒤 afplay(알림음)·osascript(데스크톱 알림)로 확장합니다.
• 같은 hooks 배열의 핸들러는 병렬 실행되므로 알림음과 데스크톱 알림을 함께 걸 수 있습니다.
• 응답마다 울리므로 장시간 태스크일 때만 켜거나 settings.local.json에 개인 설정으로 두는 것이 좋습니다.
• 다음은 도구 실행 전후에 끼어드는 PreToolUse·PostToolUse 훅입니다.