Claude Code 푸시 알림: 작업이 끝나면 바로 알려 받기

Claude Code는 20분 정도 혼자서도 잘 작업해요. 문제는 그 20분의 나머지예요. 터미널 앞에 앉아 지켜보거나, 자리를 비웠다가 돌아와 보니 3분째 권한 요청에서 멈춰 있곤 하죠.
훅이 두 문제를 모두 해결해요. Claude Code는 수명 주기의 정해진 지점마다 셸 명령을 실행하는데, 그중 세 지점이 휴대폰으로 받고 싶은 순간이에요:
- Stop: Claude가 응답을 마쳤어요. 작업이 끝났거나 질문이 있어요.
- Notification: Claude가 당신을 기다리고 있어요. 권한 요청이거나, 입력을 기다리며 유휴 상태에 들어갔어요.
- StopFailure: 요청 한도 초과나 결제 문제처럼 API 오류로 턴이 끝났어요.
이 가이드에서는 스크립트 하나로 세 가지를 모두 Pocket Alert에 연결해요. 설정에는 약 5분이면 충분해요.
준비물
- 최근 버전의 Claude Code.
jq와curl. 대부분의 리눅스 배포판에 기본으로 들어 있어요. macOS에서는brew install jq로 설치하세요.- Pocket Alert 계정과 API 키. 무료 플랜으로도 충분해요.
- 로그인한 Pocket Alert 앱을 아이폰 또는 안드로이드 휴대폰에 설치하세요.
1단계. 훅 스크립트
Claude Code는 각 훅에 JSON 객체를 stdin으로 전달해요. 필요한 필드는 hook_event_name, cwd, Stop의 last_assistant_message, Notification의 message, StopFailure의 error예요. 스크립트는 이 값을 푸시 알림으로 바꿔요:
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")
case "$(jq -r '.hook_event_name' <<<"$payload")" in
Stop)
title="Claude finished · $project"
message=$(jq -r '.last_assistant_message // "Task complete"' <<<"$payload")
level=default ;;
Notification)
title="Claude needs you · $project"
message=$(jq -r '.message' <<<"$payload")
level=high ;;
StopFailure)
title="Claude stopped · $project"
message=$(jq -r '"API error: " + (.error // "unknown")' <<<"$payload")
level=high ;;
*) exit 0 ;;
esac
jq -n --arg t "$title" --arg m "${message:0:300}" --arg l "$level" \
'{title: $t, message: $m, level: $l}' |
curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
-H "Token: $POCKETALERT_API_KEY" \
-H 'Content-Type: application/json' \
--data-binary @- >/dev/null || true
exit 0
~/.claude/hooks/pocketalert.sh로 저장하고 실행 권한을 주세요:
mkdir -p ~/.claude/hooks
chmod +x ~/.claude/hooks/pocketalert.sh
스크립트에서 겉보기보다 중요한 줄이 두 가지 있어요:
jq -n으로 JSON을 만들어요. Claude의 마지막 메시지에는 따옴표, 백틱, 줄바꿈이 가득해요. 이를 손으로 JSON 문자열에 붙여 넣으면 첫 따옴표에서 깨져요.jq는 이를 올바르게 이스케이프해요.- 끝의
exit 0과 curl 뒤의|| true. Stop 훅에서 종료 코드 2는 "멈추지 말고 계속하라"는 뜻이에요. 알림 훅은 네트워크가 끊겨 있어도 Claude를 절대 막으면 안 돼요.
Pocket Alert CLI로 보내기
Pocket Alert CLI 2.0 이상을 설치했다면 curl 부분을 명령 한 줄로 줄일 수 있어요. CLI가 텍스트를 직접 이스케이프하고, 키는 POCKETALERT_API_KEY(아래 env 블록이 설정해요) 또는 pocketalert auth에서 읽어요:
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
-t와 -m 옵션은 위치 인자 대신 그대로 사용하세요. 마크다운 목록처럼 대시(-)로 시작하는 응답은 그렇지 않으면 옵션으로 해석돼요.
2단계. 훅 등록
모든 프로젝트에 적용되도록 ~/.claude/settings.json에 훅을 추가하세요. 파일에 이미 hooks 키가 있다면 이 항목들을 그 안에 병합하세요:
{
"env": {
"POCKETALERT_API_KEY": "YOUR_API_KEY"
},
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
],
"StopFailure": [
{ "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
],
"Notification": [
{
"matcher": "permission_prompt|idle_prompt",
"hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }]
}
]
}
}
env 블록은 API 키를 셸 프로필에 넣지 않고 훅에 전달해요. 다른 곳에서 이미 POCKETALERT_API_KEY를 export하고 있다면 이 블록은 생략하세요.
Notification의 matcher는 알림 유형으로 걸러요. permission_prompt는 권한 요청이 약 6초 동안 응답 없이 기다릴 때, idle_prompt는 Claude가 작업을 끝낸 뒤 약 1분 동안 입력이 없을 때 발생해요. 터미널 세션에서는 자리를 비운 것처럼 보일 때만 두 훅이 실행되므로, 화면을 보고 있을 때는 휴대폰이 울리지 않아요. Stop에는 matcher가 없어요. Claude가 응답을 끝낼 때마다 실행돼요.
특정 저장소에만 적용하려면 같은 hooks 블록을 해당 저장소의 .claude/settings.json에 넣으세요. git에 올리고 싶지 않다면 .claude/settings.local.json을 사용하세요.
3단계. 테스트
Claude Code는 보통 설정 파일 변경을 자동으로 반영해요(/hooks에 아직 목록이 안 보이면 새 세션을 시작하세요). 간단한 작업을 맡겨 보세요:
> List the files in this directory and stop.
Claude가 작업을 끝내면 휴대폰에 Claude finished · your-project와 응답의 앞부분이 표시돼요. 아무것도 도착하지 않으면 Claude Code 안에서 /hooks를 실행해 등록된 훅을 확인하세요.
스크립트만 따로 테스트하려면 가짜 이벤트를 넣어 보세요:
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
| POCKETALERT_API_KEY=YOUR_API_KEY ~/.claude/hooks/pocketalert.sh
휴대폰에 도착하는 알림
| 이벤트 | 제목 | 본문 | 레벨 |
|---|---|---|---|
| 작업 완료 | Claude finished · api | Claude 마지막 응답의 처음 300자 | default |
| 권한 요청 | Claude needs you · api | Claude needs your permission | high |
| 입력 대기 | Claude needs you · api | Claude is waiting for your input | high |
| API 오류 | Claude stopped · api | API error: rate_limit | high |
high는 아이폰에서 시간 민감 알림으로 전달돼요. 그래서 권한 요청은 집중 모드를 뚫고 도착하고, 일반적인 '완료' 알림은 조용히 남아요. 모든 푸시는 앱의 기록과 웹 대시보드에도 남으므로, Claude가 밤새 한 작업을 거슬러 확인할 수 있어요.
내 방식으로 바꾸기
자리를 비웠을 때만. Stop은 짧은 응답처럼 지켜보고 있는 응답을 포함해 매번 실행돼요. 스크립트 맨 위에 스위치를 추가하세요:
[ -f ~/.claude/away ] || exit 0
그다음 자리를 뜰 때 touch ~/.claude/away를, 돌아오면 rm ~/.claude/away를 실행하세요. 권한 요청은 어느 경우든 받을 가치가 있으니, 검사는 Stop) 분기 안에만 넣으면 돼요.
프로젝트별로 묶기. Pocket Alert에서 프로젝트마다 애플리케이션을 만들고 JSON에 application_id를 추가하세요. 앱에서 프로젝트별로 필터링할 수 있고, 각각 기본 레벨을 따로 정할 수 있어요.
Claude를 전혀 막지 않기. "async": true 옆에 "type": "command"를 추가하면 훅이 백그라운드에서 실행돼요. 헤드리스 실행(claude -p)에서는 건너뛰세요. 백그라운드 훅은 세션이 끝나면 종료되어서 푸시가 전송되지 않을 수 있어요.
휴대폰에서 이어하기. 유료 플랜에서는 세션 ID를 담은 copy 액션 버튼으로 휴대폰에서 claude --resume <id>를 복사해, 돌아와서 붙여 넣을 수 있어요.
또는 MCP로 Claude가 직접 보내게 하기
훅은 결정적으로 동작해요. Claude가 기억하든 말든 실행되죠. 다른 방법은 Claude에게 알림 도구를 주고 언제 쓸지 Claude가 결정하게 하는 거예요. Pocket Alert MCP 서버를 추가하세요:
claude mcp add --transport http pocketalert https://mcp.pocketalert.app/mcp \
--scope user --header "Authorization: Bearer YOUR_API_KEY"
이제 "마이그레이션을 실행하고 끝나면 행 수를 푸시로 보내 줘"라고 말할 수 있어요. 그러면 Claude는 create_message를 호출하고, 그 상황에 맞게 직접 쓴 메시지를 보내요. 도구는 level과 actions도 받고, list_messages로 Claude가 이전에 보낸 메시지를 다시 읽을 수도 있어요.
두 가지를 함께 쓰세요. 반드시 받아야 하는 '완료'와 '확인 필요'는 훅으로, 실제 내용이 담긴 메시지는 MCP로 보내세요. 위험한 작업 전 승인이 필요하다면 사람 개입형 알림을 참고하세요.
알림이 오지 않을 때
- 키 확인. 위의 테스트 명령을 실행하세요. curl이
401을 반환하면 API 키가 잘못된 거예요. 응답을 보려면>/dev/null을 지우세요. - 훅이 로드됐는지 확인.
/hooks를 실행하세요. 설정 파일 변경은 보통 몇 초 안에 반영돼요. 훅이 목록에 없다면 Claude Code를 재시작하세요. - Claude Code가 사용하는 PATH에
jq가 있는지 확인. 훅은 Claude의 환경에서 실행되는데, GUI로 실행한 에디터는 Homebrew의/opt/homebrew/bin을 보지 못할 수 있어요. - 일일 한도 확인. 무료 플랜은 하루 50개 메시지를 보낼 수 있어요. 짧은 대화가 많은 긴 세션은 이를 금방 소진할 수 있어요. 위의 자리 비움 스위치가 도움이 돼요.
FAQ
VS Code와 JetBrains 확장에서도 동작하나요?
네. 확장 프로그램은 내부적으로 Claude Code를 실행하고 같은 ~/.claude/settings.json을 읽으므로, 훅이 거기서도 실행돼요.
Claude가 API 키를 볼 수 있나요?
대화 안에서는 볼 수 없어요. 훅은 대화 밖에서 실행되고, Stop과 Notification의 출력은 모델에 표시되지 않아요. 다만 env 블록은 세션 전체에 적용되므로, Claude가 실행하는 Bash 명령이 이 변수를 읽을 수 있어요. 이것이 문제라면 키를 본인만 읽을 수 있는 파일(예: ~/.config/pocketalert/key, 권한 600)에 두고, 스크립트에서 -H "Token: $(cat ~/.config/pocketalert/key)"를 사용하세요.
터미널 벨이나 데스크톱 알림과 뭐가 다른가요?
벨과 데스크톱 알림은 컴퓨터 앞에 있어야 보여요. 푸시는 어디에 있든 휴대폰에 도착하고, 기록이 남으며, Claude를 막는 요청만 집중 모드를 뚫도록 설정할 수 있어요.
300자가 아니라 전체 응답을 받을 수 있나요?
푸시에는 약 3,000자까지 담을 수 있어요. 0:300 제한을 늘리면 되지만, 푸시는 전체 답변을 읽기보다 책상으로 돌아갈지 판단하는 용도에 더 맞아요.
무료인가요?
네. 훅은 Claude Code의 기능이고, Pocket Alert 무료 플랜은 기기 한 대에서 하루 50개 메시지를 제공해요. 유료 플랜은 메시지, 기기, 액션 버튼을 더 제공해요.
API 키 발급받기하고 스크립트를 넣은 뒤, Claude가 차례를 알려 주게 하세요.