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

> Claude Code가 작업을 끝내거나, 권한을 기다리거나, 오류로 멈추면 휴대폰으로 푸시 알림을 받으세요. 훅 스크립트 하나, 이벤트 세 개, 플러그인은 필요 없어요.

*11.10.2026*

<!-- source: https://pocketalert.app/ko/blog/claude-code-push-notifications -->

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 키](/account/apikeys). 무료 플랜으로도 충분해요.
- 로그인한 Pocket Alert 앱을 [아이폰 또는 안드로이드](/get-app) 휴대폰에 설치하세요.

## 1단계. 훅 스크립트

Claude Code는 각 훅에 JSON 객체를 stdin으로 전달해요. 필요한 필드는 `hook_event_name`, `cwd`, Stop의 `last_assistant_message`, Notification의 `message`, StopFailure의 `error`예요. 스크립트는 이 값을 푸시 알림으로 바꿔요:

```bash
#!/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`로 저장하고 실행 권한을 주세요:

```bash
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](/tools/cli) 2.0 이상을 설치했다면 curl 부분을 명령 한 줄로 줄일 수 있어요. CLI가 텍스트를 직접 이스케이프하고, 키는 `POCKETALERT_API_KEY`(아래 `env` 블록이 설정해요) 또는 `pocketalert auth`에서 읽어요:

```bash
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
```

`-t`와 `-m` 옵션은 위치 인자 대신 그대로 사용하세요. 마크다운 목록처럼 대시(-)로 시작하는 응답은 그렇지 않으면 옵션으로 해석돼요.

## 2단계. 훅 등록

모든 프로젝트에 적용되도록 `~/.claude/settings.json`에 훅을 추가하세요. 파일에 이미 `hooks` 키가 있다면 이 항목들을 그 안에 병합하세요:

```json
{
  "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`에 아직 목록이 안 보이면 새 세션을 시작하세요). 간단한 작업을 맡겨 보세요:

```text
> List the files in this directory and stop.
```

Claude가 작업을 끝내면 휴대폰에 **Claude finished · your-project**와 응답의 앞부분이 표시돼요. 아무것도 도착하지 않으면 Claude Code 안에서 `/hooks`를 실행해 등록된 훅을 확인하세요.

스크립트만 따로 테스트하려면 가짜 이벤트를 넣어 보세요:

```bash
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | POCKETALERT_API_KEY=YOUR_API_KEY ~/.claude/hooks/pocketalert.sh
```

## 휴대폰에 도착하는 알림

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>이벤트</th><th>제목</th><th>본문</th><th>레벨</th></tr></thead>
<tbody>
<tr><th>작업 완료</th><td>Claude finished · api</td><td>Claude 마지막 응답의 처음 300자</td><td>default</td></tr>
<tr><th>권한 요청</th><td>Claude needs you · api</td><td>Claude needs your permission</td><td>high</td></tr>
<tr><th>입력 대기</th><td>Claude needs you · api</td><td>Claude is waiting for your input</td><td>high</td></tr>
<tr><th>API 오류</th><td>Claude stopped · api</td><td>API error: rate_limit</td><td>high</td></tr>
</tbody>
</table>
</div>

`high`는 아이폰에서 시간 민감 알림으로 전달돼요. 그래서 권한 요청은 집중 모드를 뚫고 도착하고, 일반적인 '완료' 알림은 조용히 남아요. 모든 푸시는 앱의 기록과 [웹 대시보드](/messages)에도 남으므로, Claude가 밤새 한 작업을 거슬러 확인할 수 있어요.

## 내 방식으로 바꾸기

**자리를 비웠을 때만.** Stop은 짧은 응답처럼 지켜보고 있는 응답을 포함해 매번 실행돼요. 스크립트 맨 위에 스위치를 추가하세요:

```bash
[ -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` [액션 버튼](https://info.pocketalert.app/features/action-buttons.html)으로 휴대폰에서 `claude --resume <id>`를 복사해, 돌아와서 붙여 넣을 수 있어요.

## 또는 MCP로 Claude가 직접 보내게 하기

훅은 결정적으로 동작해요. Claude가 기억하든 말든 실행되죠. 다른 방법은 Claude에게 알림 도구를 주고 언제 쓸지 Claude가 결정하게 하는 거예요. [Pocket Alert MCP 서버](/tools/mcp)를 추가하세요:

```bash
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로 보내세요. 위험한 작업 전 승인이 필요하다면 [사람 개입형 알림](/blog/human-in-the-loop-notifications)을 참고하세요.

## 알림이 오지 않을 때

- **키 확인.** 위의 테스트 명령을 실행하세요. 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 키 발급받기](/signup)하고 스크립트를 넣은 뒤, Claude가 차례를 알려 주게 하세요.
