결론 / TL;DR

Claude Code의 hooks를 사용하면, "태스크가 끝났다", "세션이 종료되었다"는 타이밍에 임의의 명령어를 실행할 수 있습니다. 이를 사용하여 작업 완료를 Slack에 알림하도록 설정했더니, 긴 처리 과정을 안심하고 방치할 수 있게 되었습니다.

해야 할 일은 딱 세 가지뿐입니다.

• Slack의 Incoming Webhook URL 취득
• 알림용 쉘 스크립트(shell script) 하나 배치
• .claude/settings.local.json의 hooks에 등록

복사해서 바로 사용할 수 있는 형태로 모두 올립니다.

배경 · 무엇 때문에 고민했는가

Claude Code에 긴 태스크를 던지면 완료까지 몇 분에서 십수 분이 걸릴 때가 있습니다. 그동안 나도 모르게 "끝났나?" 하고 몇 번이고 화면을 확인하게 되어 집중력이 깨지곤 했습니다. 그렇다고 방치하자니, 끝난 것을 알아채지 못해 시간을 낭비하게 됩니다.

"끝나면 알려주면 좋을 텐데" —— 그것을 hooks로 실현합니다.

한 일

1. Slack의 Incoming Webhook 취득

• Slack 워크스페이스에서 Apps → Incoming Webhooks를 추가 - 알림을 보내고 싶은 채널을 선택
• 발행된 Webhook URL을 복사 (https://hooks.slack.com/services/T.../B.../XXXX 형태)

⚠️ 이 URL은 **시크릿(secret)**입니다. 리포지토리(repository)에 커밋하지 마세요 (후술).

2. 알림 스크립트 배치

.claude/slack_notify.sh로 저장합니다. .env에서 Webhook URL을 읽어와, 이벤트 종류에 따라 색상과 이모지를 바꿔 Slack으로 던지기만 하는 스크립트입니다.

#!/bin/bash
# Usage: ./slack_notify.sh [event_type] [message] [status]
# Windows(Git Bash/MINGW64)에서 UTF-8을 확실히 하기 위해 명시
...

Webhook URL은 .claude/.env에 두고, .gitignore에 반드시 추가합니다.

# .claude/.env
SLACK_WEBHOOK_URL=https://hooks.slack.com/services/YOUR/WEBHOOK/URL

3. hooks에 등록하기

.claude/settings.local.json의 hooks에 Stop(태스크 완료)과 SessionEnd(세션 종료)를 등록합니다.

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

• Stop: Claude가 응답을 마친 타이밍(=1개 태스크 완료)에 발화
• SessionEnd: 세션이 종료되었을 때 발화

결과

태스크를 던져두고 다른 작업으로 넘어갔다가, Slack에 🎯이 날아오면 돌아오는 흐름이 되었습니다. "끝났는지 궁금해서 화면을 보러 가는" 일이 없어졌고, 대기 시간을 다른 작업에 사용할 수 있습니다. 알림에는 Event / Status / Message / Project / 시간이 포함되므로, 여러 프로젝트를 병행하고 있어도 "어느 것이 끝났는지" 알 수 있습니다.

주의할 점 (ハマりどころ)

• 스크립트 경로 지정에 주의. command를 ./slack_notify.sh ...라고 쓰면, hook은 프로젝트의 현재 디렉토리(current directory)에서 실행되기 때문에 .claude/ 내부의 스크립트를 찾지 못할 수 있습니다. 프로젝트 루트 기점으로 bash .claude/slack_notify.sh ...라고 쓰는 것이 안전합니다.
• Windows(Git Bash)의 UTF-8. 일본어 메시지가 글자 깨짐 현상이 발생하는 경우, LC_ALL=C.UTF-8 명시와 printf '%s' ... | curl --data-binary @-를 통한 전송이 효과적입니다. -d로 전달하면 줄바꿈이나 인코딩 문제로 깨지기 쉽습니다.
• Webhook URL은 절대로 커밋하지 말 것. .env에 넣고 .gitignore로 제외하세요. 공개 리포지토리에 유출하면 누구나 해당 채널에 게시물을 올릴 수 있게 됩니다.
• 알림이 너무 많으면 시끄럽다. Stop...

은 매 태스크(task)마다 울리기 때문에, 너무 자주 울린다면 SessionEnd만 사용하도록 하는 등 입도(granularity)를 조정하는 것이 좋습니다.

요약

hooks는 "Claude Code의 라이프사이클(lifecycle)에 명령어를 삽입하는" 단순한 메커니즘이지만, Slack 알림과 결합하는 것만으로도 경험이 달라집니다. 같은 방식으로 배포 완료 알림이나 테스트 결과 알림 등 응용이 가능합니다.

우선 Stop에 한 줄을 추가하는 것부터 시도해 보세요.

개발 로그나 LLM 활용 팁은 X(@box222box)에서도 발신하고 있습니다.

Discussion