블로그로 돌아가기

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

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 · apiClaude 마지막 응답의 처음 300자default
권한 요청Claude needs you · apiClaude needs your permissionhigh
입력 대기Claude needs you · apiClaude is waiting for your inputhigh
API 오류Claude stopped · apiAPI error: rate_limithigh

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가 차례를 알려 주게 하세요.

이 글 공유하기