Claude Code 작업 완료 알림 + 클릭 시 VSCode 포커스 자동화

Claude Code한테 긴 작업 시켜놓고 다른 거 하다 보면 끝난 줄 모르고 지나가는 경우가 많아요. Stop 훅으로 macOS 알림을 쏘고, 알림을 클릭하면 VSCode로 포커스까지 돌아오게 만드는 세팅이에요. 많이 공유되는 terminal-notifier 방법은 최근 macOS에서 권한·클릭 이벤트가 꼬이는 함정이 있어서, 후계 도구인 alerter를 쓰는 게 정답이에요.

준비물

• macOS (알림센터)
• Claude Code (Stop 훅 지원 버전)
• 시스템 설정 → 알림 → 알림 요약이 꺼져 있어야 해요. 켜져 있으면 어떤 도구를 써도 실시간 알림이 안 떠요.

• curl, unzip, bash (macOS 기본)

스텝

1. alerter 바이너리 내려받기

Homebrew 포뮬러가 없어서 GitHub 릴리즈 zip을 받아 ~/.claude/bin/에 풀어요.

mkdir -p ~/.claude/bin ~/.claude/hooks
cd /tmp
curl -sL -o alerter.zip https://github.com/vjeantet/alerter/releases/download/v26.5/alerter-26.5.zip
unzip -o alerter.zip -d alerter-extract
mv alerter-extract/alerter ~/.claude/bin/alerter
chmod +x ~/.claude/bin/alerter
xattr -d com.apple.quarantine ~/.claude/bin/alerter 2>/dev/null

xattr -d 한 줄은 "확인되지 않은 개발자" Gatekeeper 차단을 풀어주는 거예요.

2. 권한 한 번 허용하기

처음 실행하면 macOS 알림 권한 다이얼로그가 떠요. "허용" 눌러주고 끝. 한 번만 하면 돼요.

~/.claude/bin/alerter --title 'Claude Code' --message '권한 허용 테스트' --timeout 10 &

3. 훅 스크립트 작성

~/.claude/hooks/notify-done.sh를 아래 내용으로 만들어요. 핵심은 alerter가 알림 클릭 시 stdout으로 @CONTENTCLICKED를 반환한다는 점, 그걸 보고 VSCode를 open -a로 올려요.

#!/bin/bash
RESULT=$("$HOME/.claude/bin/alerter" \
  --title 'Claude Code' \
  --message '작업이 완료되었습니다' \
  --sound default \
  --timeout 60)

if [ "$RESULT" = "@CONTENTCLICKED" ]; then
  open -a "Visual Studio Code"
fi

실행 권한 부여.

chmod +x ~/.claude/hooks/notify-done.sh

4. Claude Code Stop 훅 등록

~/.claude/settings.json의 hooks.Stop에 아래 entry를 추가해요. 이미 있으면 command만 바꾸면 돼요.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "nohup bash \"$HOME/.claude/hooks/notify-done.sh\" >/dev/null 2>&1 &"
          }
        ]
      }
    ]
  }
}

nohup ... &로 반드시 백그라운드 분리해야 해요. alerter는 클릭되거나 타임아웃될 때까지 프로세스가 살아 있어서, 안 떼면 Claude Code가 다음 입력을 못 받고 멈춘 것처럼 보여요.

확인 방법

Claude Code에서 아무 작업이나 시켜서 끝날 때까지 기다려보세요.

• 작업 종료 시점에 "Claude Code 작업이 완료되었습니다" 알림이 뜨면 성공
• 알림을 클릭하면 VSCode 창이 포커스 이동
• 60초 무시하면 알림이 사라지지만 알림센터엔 남아 있음
• 알림이 뜬 동안에도 Claude Code는 계속 사용 가능

응용

• 메시지/사운드/타임아웃: notify-done.sh의 --message, --sound, --timeout 값만 바꾸면 돼요.
• 에디터 변경: open -a "Visual Studio Code" 자리를 open -a "Cursor" 같이 교체.
• 특정 프로젝트 열기: open -a 대신 code /path/to/project로 하면 지정 폴더가 열려요.
• 작업 종류별 분기: $CLAUDE_TRANSCRIPT_PATH 등 Stop 훅 환경변수를 읽어서 조건부로 다른 알림을 쏠 수도 있어요.

트러블슈팅

알림이 아예 안 뜬다: 거의 100% "알림 요약"이 켜져 있어요. 시스템 설정 → 알림에서 요약을 끄고 다시 시도.

알림 허용을 눌렀는데도 안 뜬다: terminal-notifier 잔재가 섞여 있을 가능성. terminal-notifier 2.0.0은 오래된 알림 API를 써서 최근 macOS에서 번들 ID 권한 매칭이 꼬여요. 시스템 설정에는 "허용"으로 보이지만 실제론 막혀 있는 상태. terminal-notifier를 쓰는 기존 훅이 있다면 alerter 버전으로 완전히 교체해요.

클릭해도 VSCode가 안 올라온다: -sender com.microsoft.VSCode 같은 꼼수 플래그를 붙였는지 확인. 이 플래그가 있으면 클릭 이벤트가 VSCode로 먼저 가버려서 스크립트의 open -a가 먹지 않아요. 이번 레시피의 스크립트처럼 -sender 없이 쓰세요.

Claude Code가 멈춘 것처럼 보인다: settings.json에서 nohup ... &를 빠뜨렸을 때 나타나요. alerter 프로세스가 훅 호출을 붙잡고 있어서 그래요. nohup과 끝의 & 둘 다 있어야 해요.