Gemini CLI のプッシュ通知:完了か、承認待ちか

Gemini CLI は単体でも通知できますが、ターミナル上に限られます。general.enableNotifications を有効にすると、処理が終わったときや入力が必要なときにデスクトップ通知またはベル音が鳴ります。パソコンの前にいて、ターミナルが別のタブにあるときには役立ちます。ただし、パソコンから離れているときには届きません。
フックを使えばこの問題を解決できます。v0.26 以降はフックがデフォルトで有効になっており、そのうち 2 つのイベントはスマホへのプッシュ通知にぴったり合います。
- AfterAgent:Gemini がターンを終えたとき。ペイロードには応答が含まれます。
- Notification:Gemini がツールの実行許可を求めているとき。
このガイドでは、この 2 つを Pocket Alert 経由でスマホに送ります。
どの Gemini CLI かについて
Google のドキュメントによると、2026年6月18日以降、無料枠と Google One プランでは Gemini CLI が Antigravity CLI に置き換えられています。Gemini CLI 自体は、有料の Gemini API キー、Vertex AI、またはエンタープライズ向けアクセスで引き続き利用でき、このガイドもそれを対象としています。Antigravity CLI を使っている場合は、フックについてそのドキュメントを確認してください。
必要なもの
キーはファイルに保存してください。環境変数のリダクションが有効な場合や GitHub Actions で実行している場合、Gemini CLI はフックを実行する前に、名前に KEY や TOKEN を含む環境変数を取り除くことがあります。ファイルから読み込むキーはこの影響を受けません。
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 オブジェクトを標準入力で渡します。AfterAgent では prompt_response が加わり、Notification では notification_type と message が加わります。次の内容を ~/.gemini/hooks/pocketalert.sh として保存してください。
#!/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 '{}'
chmod +x ~/.gemini/hooks/pocketalert.sh
Gemini CLI はフックの標準出力を JSON として解析するため、スクリプトは {} だけを出力し、それ以外は出しません。curl の出力は /dev/null に送っています。AfterAgent フックが終了コード 2 を返すと応答が拒否され、Gemini が再試行するため、スクリプトではこの値を返さないようにしています。
Pocket Alert CLI を使う場合
Pocket Alert CLI 2.0 以降をインストールしていれば、curl のブロックは 1 行のコマンドに短縮できます。CLI がテキストのエスケープを自動で行い、キーは pocketalert auth から読み込みます。そのため、前述の環境変数の削除も問題になりません。
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
位置引数ではなく -t と -m を使ってください。Markdown のリストのように、ダッシュで始まる応答がオプションとして解釈されてしまうのを防げます。
手順 2. フックを登録する
hooks に、既存の内容とマージする形で ~/.gemini/settings.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. 動作を確認する
まず、模擬イベントを使ってスクリプトを実行します。
echo '{"hook_event_name":"AfterAgent","cwd":"/tmp/demo","prompt_response":"Hook test"}' \
| ~/.gemini/hooks/pocketalert.sh
次に Gemini CLI を起動し、実行許可が必要なツール呼び出しで終わるタスクを与えます。たとえば「notes.txt という名前のファイルを作成して」のような指示です。待機中には Gemini needs approval が届き、許可してターンが終わると Gemini finished が届きます。
スマホに届く内容
| イベント | タイトル | 本文 | レベル |
|---|---|---|---|
| ターン完了 | Gemini finished · api | 応答の最初の 300 文字 | default |
| ツールの実行許可 | Gemini needs approval · api | Gemini CLI からの許可メッセージ | high |
high は iPhone では時間に敏感な通知として届くため、承認依頼は集中モード中でも届きます。すべてのプッシュ通知はアプリとWebダッシュボードに残ります。
または MCP 経由で Gemini に送らせる
Pocket Alert MCP サーバー を使うと、Gemini は指示されたタイミングで、自分で書いた内容のプッシュ通知を送れます。コマンドラインから追加してください。
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 を起動するシェルで変数をエクスポートしておいてください。--scope user を省略すると、サーバーは現在のプロジェクトにだけ追加されます。
~/.gemini/settings.json には次の内容が追加されます。
{
"mcpServers": {
"pocketalert": {
"url": "https://mcp.pocketalert.app/mcp",
"type": "http",
"headers": { "Authorization": "Bearer $POCKETALERT_API_KEY" }
}
}
}
Gemini CLI 内で /mcp を実行すると、サーバーとそのツールを確認できます。そのうえで「マイグレーションを実行して、終わったら行数を通知して」のようなプロンプトを与えると、最後に create_message の呼び出しで終わります。
通知が届かない場合
- テストコマンドを実行する。 プッシュ通知が届かない場合は、キーかネットワークに問題があります。curl のレスポンスを確認するには
>/dev/null 2>&1を削除してください。 - フックが有効か確認する。 デフォルトでは有効ですが、設定に
hooksConfig.enabled: falseがあるとフックが無効になります。 commandのパスを確認する。 絶対パスで指定されていて、スクリプトに実行権限があるかを確認してください。- 標準出力を確認する。 標準出力に JSON 以外の内容があると、Gemini CLI はフックの結果を無視します。スクリプト内で他に出力している箇所がないか確認してください。
FAQ
general.enableNotifications との違いは何ですか?
この設定は、Gemini が入力を求めているときや処理が終わったときに、パソコンへターミナル通知を送ります。フックではどんなコマンドも実行できるため、スマホに届けたり、履歴を残したり、優先度レベルを使ったりできます。
スマホからツール呼び出しを承認できますか?
このスクリプトではできません。Gemini が待機中であることを知らせるだけで、承認はターミナルで行います。BeforeTool フックではツール呼び出しをブロックできるため、スマホから呼び出すエンドポイントを使えば承認ゲートを作ることも可能です。その方法は Human-in-the-loop 通知 で説明しています。
GitHub Actions でも使えますか?
使えます。その場合はキーをファイルに保存する方法が重要です。GitHub Actions では、Gemini CLI がフックの環境から、名前に KEY や TOKEN を含む変数を取り除きます。前のステップでシークレットからキーをファイルに書き出してください。
無料で使えますか?
フックは Gemini CLI の機能であり、Pocket Alert の無料プランでは 1 台のデバイスに対して 1 日 50 件のメッセージまで利用できます。Gemini 自体は、前述のとおり CLI の利用に有料の API キーかエンタープライズ向けアクセスが必要です。
API キーを取得し、フックを設定して、Gemini が入力を必要としたときにすぐ気づけるようにしましょう。