# Gemini CLI 푸시 알림: 작업 완료와 승인 대기를 휴대폰으로

> Gemini CLI가 한 턴을 끝내거나 도구 실행 승인을 요청하면 휴대폰으로 푸시 알림을 보내세요. settings.json의 훅 두 개, 스크립트 하나, 그리고 Pocket Alert MCP 서버면 충분합니다.

*15.10.2026*

<!-- source: https://pocketalert.app/ko/blog/gemini-cli-notifications -->

Gemini CLI는 자체적으로도 알림을 보낼 수 있지만, 터미널 안에서만 동작합니다. `general.enableNotifications`를 켜면 작업이 끝나거나 사용자의 응답이 필요할 때 데스크톱 알림이나 벨 소리로 알려 줍니다. 컴퓨터 앞에 있고 터미널이 다른 탭에 있을 때는 도움이 됩니다. 하지만 자리를 비우면 아무 소용이 없습니다.

훅으로 이 간극을 메울 수 있습니다. v0.26부터 훅은 기본으로 켜져 있고, 그중 두 이벤트가 바로 휴대폰 푸시 알림이 필요한 순간입니다.

- **AfterAgent**: Gemini가 한 턴을 끝냈습니다. 페이로드에 응답이 포함됩니다.
- **Notification**: Gemini가 도구를 실행하려면 권한을 요청하고 있습니다.

이 가이드는 두 이벤트를 Pocket Alert를 통해 휴대폰으로 보내는 방법을 다룹니다.

## 어떤 Gemini CLI인지 확인하세요

Google 문서에 따르면 2026년 6월 18일부터 무료 티어와 Google One 플랜에서는 Gemini CLI가 Antigravity CLI로 대체되었습니다. Gemini CLI는 유료 Gemini API 키, Vertex AI, 또는 엔터프라이즈 액세스와 함께 계속 제공되며, 이 가이드는 이 버전을 기준으로 합니다. Antigravity CLI를 사용 중이라면 훅 관련 내용은 해당 문서를 확인하세요.

## 준비물

- Gemini CLI v0.26 이상
- `jq`와 `curl`
- Pocket Alert 계정, [API 키 페이지](/account/apikeys)에서 발급받은 API 키, 그리고 휴대폰에 설치한 [앱](/get-app). 무료 플랜으로도 충분합니다.

키는 파일에 저장하세요. 환경 변수 редакци(redaction)가 켜져 있거나 GitHub Actions에서 실행할 때는 Gemini CLI가 훅을 실행하기 전에 이름에 `KEY`나 `TOKEN`이 들어간 환경 변수를 제거할 수 있습니다. 파일에서 읽은 키는 영향을 받지 않습니다.

```bash
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
```

## 1단계. 훅 스크립트

Gemini CLI는 각 훅에 `hook_event_name`과 `cwd`가 담긴 JSON 객체를 stdin으로 전달합니다. `AfterAgent`에는 `prompt_response`가, `Notification`에는 `notification_type`과 `message`가 추가로 들어옵니다. 다음 내용을 `~/.gemini/hooks/pocketalert.sh`로 저장하세요.

```bash
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  AfterAgent)
    title="Gemini finished · $project"
    message=$(jq -r '.prompt_response // "Turn complete"' <<<"$payload")
    level=default ;;
  Notification)
    title="Gemini needs approval · $project"
    message=$(jq -r '.message // "Waiting for tool permission"' <<<"$payload")
    level=high ;;
  *) echo '{}'; 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 5 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true

echo '{}'
```

```bash
chmod +x ~/.gemini/hooks/pocketalert.sh
```

Gemini CLI는 훅의 stdout을 JSON으로 파싱하므로, 스크립트는 `{}`만 출력하고 curl의 출력은 `/dev/null`로 보냅니다. `AfterAgent` 훅이 종료 코드 2를 반환하면 응답이 거부되고 Gemini가 재시도하므로, 스크립트는 이 코드를 절대 반환하지 않습니다.

### Pocket Alert CLI를 사용하는 경우

[Pocket Alert CLI](/tools/cli) 2.0 이상을 설치했다면 curl 블록을 명령 하나로 줄일 수 있습니다. CLI가 텍스트 이스케이프를 직접 처리하고, 키는 `pocketalert auth`에서 가져오므로 위에서 설명한 환경 변수 제거 문제도 피할 수 있습니다.

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

`-t`와 `-m` 옵션을 쓰고 위치 인수는 쓰지 마세요. 마크다운 목록처럼 하이픈으로 시작하는 응답은 그렇지 않으면 옵션으로 해석됩니다.

## 2단계. 훅 등록

`hooks`에 기존 내용과 병합하여 `~/.gemini/settings.json` 블록을 추가하세요.

```json
{
  "hooks": {
    "AfterAgent": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "pocketalert-done",
            "type": "command",
            "command": "/Users/you/.gemini/hooks/pocketalert.sh",
            "timeout": 10000
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "name": "pocketalert-approval",
            "type": "command",
            "command": "/Users/you/.gemini/hooks/pocketalert.sh",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}
```

`/Users/you`는 본인의 홈 디렉터리로 바꾸세요. 여기서 `timeout`은 밀리초 단위입니다. 다른 에이전트와 달리 초가 아니라는 점에 유의하세요. 특정 프로젝트에만 적용하려면 같은 블록을 저장소의 `.gemini/settings.json`에 넣으세요. Gemini CLI는 신뢰된 폴더에서만 프로젝트 훅을 실행합니다.

## 3단계. 테스트

먼저 가짜 이벤트로 스크립트를 실행해 보세요.

```bash
echo '{"hook_event_name":"AfterAgent","cwd":"/tmp/demo","prompt_response":"Hook test"}' \
  | ~/.gemini/hooks/pocketalert.sh
```

그다음 Gemini CLI를 실행하고, 승인이 필요한 도구 호출로 끝나는 작업을 주세요. 예를 들어 "notes.txt라는 파일을 만들어 줘"처럼 요청합니다. 승인을 기다리는 동안에는 **Gemini 승인 필요** 알림이, 승인하여 턴이 끝나면 **Gemini 작업 완료** 알림이 도착합니다.

## 휴대폰에 도착하는 내용

<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>Gemini 작업 완료 · api</td><td>응답의 처음 300자</td><td>default</td></tr>
<tr><th>도구 권한</th><td>Gemini 승인 필요 · api</td><td>Gemini CLI의 권한 요청 메시지</td><td>high</td></tr>
</tbody>
</table>
</div>

`high` 레벨 알림은 iPhone에서 시간 민감 알림으로 전달되므로, 승인 요청이 집중 모드에서도 도착합니다. 모든 푸시 알림은 앱과 웹 대시보드에 그대로 남습니다.

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

[Pocket Alert MCP 서버](/tools/mcp)를 사용하면, Gemini가 사용자가 요청한 시점에 스스로 작성한 푸시 알림을 보낼 수 있습니다. 명령줄에서 다음과 같이 추가하세요.

```bash
gemini mcp add --scope user --transport http \
  --header 'Authorization: Bearer $POCKETALERT_API_KEY' \
  pocketalert https://mcp.pocketalert.app/mcp
```

작은따옴표를 쓰면 `$POCKETALERT_API_KEY`가 설정 파일에 키 값 그대로 기록되지 않고 변수 형태로 남습니다. Gemini CLI는 연결할 때 이 변수를 확장하므로, `gemini`를 실행하는 셸에서 변수를 export해 두세요. `--scope user`를 빼면 서버가 현재 프로젝트에만 추가됩니다.

결과로 `~/.gemini/settings.json`은 다음과 같습니다.

```json
{
  "mcpServers": {
    "pocketalert": {
      "url": "https://mcp.pocketalert.app/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer $POCKETALERT_API_KEY" }
    }
  }
}
```

Gemini CLI 안에서 `/mcp`를 실행하면 서버와 도구 목록을 확인할 수 있습니다. 그다음 "마이그레이션을 실행하고 끝나면 행 개수를 푸시로 보내 줘"처럼 요청하면, 마지막에 `create_message` 호출이 실행됩니다.

## 알림이 오지 않을 때

- **테스트 명령을 실행해 보세요.** 푸시가 오지 않으면 키나 네트워크 문제입니다. `>/dev/null 2>&1`을 지우면 curl의 응답을 볼 수 있습니다.
- **훅이 켜져 있는지 확인하세요.** 기본값은 켜짐이지만, 설정에 `hooksConfig.enabled: false`가 있으면 꺼집니다.
- **`command`의 경로가 절대 경로인지, 스크립트에 실행 권한이 있는지 확인하세요.**
- **stdout을 확인하세요.** stdout에 JSON 이외의 내용이 나오면 Gemini CLI가 훅의 결과를 무시합니다. 스크립트 안에서 다른 내용이 출력되지 않는지 확인하세요.

## 자주 묻는 질문

### `general.enableNotifications`와는 무엇이 다른가요?

해당 설정은 Gemini가 사용자를 필요로 하거나 작업을 끝냈을 때 컴퓨터에 터미널 알림을 보냅니다. 훅은 임의의 명령을 실행할 수 있어서 휴대폰으로 알림을 보내고, 기록을 남기고, 우선순위 레벨을 지정할 수 있습니다.

### 휴대폰에서 도구 호출을 승인할 수 있나요?

이 스크립트로는 불가능합니다. Gemini가 대기 중이라는 사실만 알려 주며, 승인은 터미널에서 해야 합니다. `BeforeTool` 훅으로 도구 호출을 차단할 수 있으므로, 휴대폰이 호출하는 엔드포인트를 두면 승인 게이트를 구현할 수 있습니다. 구체적인 패턴은 [사람 개입형 알림](/blog/human-in-the-loop-notifications)에서 확인하세요.

### GitHub Actions에서도 작동하나요?

네, 그리고 여기서는 키 파일 방식이 중요합니다. GitHub Actions에서는 Gemini CLI가 이름에 `KEY`나 `TOKEN`이 들어간 변수를 훅의 환경에서 제거합니다. 이전 단계에서 시크릿의 키를 파일에 써 두세요.

### 무료인가요?

훅은 Gemini CLI의 기능이고, Pocket Alert 무료 플랜은 기기 한 대에 하루 50개의 메시지를 제공합니다. Gemini 자체는 위에서 언급했듯이 CLI 사용을 위해 유료 API 키나 엔터프라이즈 액세스가 필요합니다.

[API 키 발급받기](/signup), 훅을 추가하고, Gemini가 도움이 필요할 때 알림을 받으세요.
