Codex CLI の通知:タスク完了時にスマホへプッシュ通知

Codex CLI は、ターミナルを見ていれば完了をすでに知らせてくれます。内蔵の通知はターミナルのエスケープコードを使うもので、対応しているターミナルならデスクトップバナーが表示され、非対応なら通知音が鳴ります。どちらも、席を離れたあとには届きません。
Codex はライフサイクルの特定のタイミングで独自のコマンドを実行できます。スマホへのプッシュ通知に必要なのはこの仕組みだけです。このガイドでは、Codex がターンを完了したときと、承認を求めて停止したときの 2 種類の通知を送るように設定します。
Codex がコマンドを実行する 2 つの方法
- Hooks:現在の仕組みです。
hooks.jsonで設定し、デフォルトで有効になっています。Stop、PermissionRequest、PreToolUse、SessionEndなどのイベントがあります。コマンドにはイベントが JSON として標準入力で渡されます。 notify:config.tomlにある従来の設定です。agent-turn-completeという 1 つのイベントでのみ実行され、JSON はコマンドの最後の引数として渡されます。今も動作しますが、Codex のソースコードでは従来の仕組みとして扱われています。
Hooks を使うことをおすすめします。notify の方法は、古い環境向けに末尾で紹介します。
必要なもの
API キーは、自分だけが読める場所に保存しておきましょう。そうすればシェルの履歴や環境変数に残りません。
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
ステップ 1. Hook スクリプト
次の内容を ~/.codex/hooks/pocketalert.sh として保存します。
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")
case "$(jq -r '.hook_event_name' <<<"$payload")" in
Stop)
title="Codex finished · $project"
message=$(jq -r '.last_assistant_message // "Turn complete"' <<<"$payload")
level=default ;;
PermissionRequest)
title="Codex needs approval · $project"
message=$(jq -r '"Wants to run " + (.tool_name // "a tool")' <<<"$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: $(cat ~/.config/pocketalert/key)" \
-H 'Content-Type: application/json' \
--data-binary @- >/dev/null 2>&1 || true
exit 0
chmod +x ~/.codex/hooks/pocketalert.sh
Codex は hook の出力に厳格です。Stop の場合は、標準出力に何も出さないか JSON を出すかのどちらかが求められます。終了コード 2 を返すと、停止せずに処理を続けるよう Codex に伝わります。そのため、curl の出力はすべて /dev/null に捨て、スクリプトは必ず exit 0 で終わるようにしています。
PermissionRequest の hook は、Codex に代わって許可または拒否を返すこともできます。このスクリプトはどちらも行いません。何も出力しないので、Codex は通常の承認プロンプトを表示し、あなたには「承認待ちです」というプッシュ通知が届きます。
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. Hook を登録する
~/.codex/hooks.json を作成します。
{
"hooks": {
"Stop": [
{
"hooks": [
{ "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
]
}
],
"PermissionRequest": [
{
"hooks": [
{ "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
]
}
]
}
}
ホームディレクトリにあるファイルはどこでも適用されます。リポジトリ内の .codex/hooks.json はそのプロジェクトにだけ適用されますが、そのプロジェクトを信頼済みに設定した後に限られます。
Hooks はデフォルトで有効です。以前に無効にしていた場合は、hooks = false の [features] テーブルから ~/.codex/config.toml を削除してください。
Codex は、レビューして信頼した hooks だけを実行します。次に起動したとき、新しい hooks はレビューが必要だと警告が表示されます。/hooks を開いて 2 つのエントリを確認し、信頼してください。後で内容を変更すると、再び信頼されるまで Codex はそれらをスキップします。
ステップ 3. テストする
任意のプロジェクトで Codex を起動し、短いタスクを与えます。
> Summarise README.md in one sentence.
ターンが終わると、スマホにCodex finished · your-project と要約つきの通知が表示されます。承認が必要なコマンドの実行を依頼すると、優先度の高い 2 つ目の通知Codex needs approval が届きます。
Codex を使わずにスクリプトだけをテストするには、次のコマンドを実行します。
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
| ~/.codex/hooks/pocketalert.sh
スマホに届く内容
| イベント | タイトル | 本文 | レベル |
|---|---|---|---|
| ターン完了 | Codex finished · api | 最後の返信の先頭 300 文字 | default |
| 承認が必要 | Codex needs approval · api | Wants to run Bash | high |
high は iPhone で時間に敏感な通知として配信されるため、承認の通知は集中モードでも届きます。一方、通常の「完了」の通知は静かなままです。どちらの通知もアプリの履歴とウェブのダッシュボードに残ります。
従来の方法:notify
お使いの Codex が hooks に対応していない場合、または既に notify を使っている場合は、いくつか変更すれば動作します。Codex はイベントを標準入力ではなく最後の引数として渡し、キーはケバブケースになり、報告されるのは完了したターンだけです。
#!/usr/bin/env bash
event="${@: -1}"
[ "$(jq -r '.type' <<<"$event")" = "agent-turn-complete" ] || exit 0
jq -n --arg m "$(jq -r '."last-assistant-message" // "Turn complete"' <<<"$event" | cut -c1-300)" \
'{title: "Codex finished", message: $m}' |
curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
-H "Token: $(cat ~/.config/pocketalert/key)" \
-H 'Content-Type: application/json' \
--data-binary @- >/dev/null 2>&1 || true
# ~/.codex/config.toml
notify = ["/Users/you/.codex/notify-pocketalert.sh"]
notify には承認のイベントがありません。Codex が停止して待っている状態を知りたい場合は、hooks を使ってください。
MCP 経由で Codex に送信させる
Hooks は決まったイベントで実行されます。Codex に何を通知するかを判断させたい場合は、Pocket Alert MCP サーバーを ~/.codex/config.toml に追加します。
[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"
コマンドラインから追加することもできます。
codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
--bearer-token-env-var POCKETALERT_API_KEY
Codex を起動するシェルで POCKETALERT_API_KEY をエクスポートしてください。そのうえで「テストスイートを実行して、失敗したものをプッシュ通知で教えて」のようなプロンプトを与えると、Codex 自身が作成した要約を使って create_message を呼び出します。このツールは level と actions も受け取れます。
通知が届かない場合
- テストコマンドを実行してください。 テストでは動くのに本番で届かない場合は、hook の登録に問題があります。動かない場合は、
>/dev/null 2>&1を削除すると curl のエラーが見えます。401はキーが間違っていることを意味します。 - Hooks が信頼されているか確認してください。 Codex で
/hooksを開いてください。信頼されていない、または変更された hooks はスキップされます。 - プロジェクトが信頼されているか確認してください。
hooks.jsonをリポジトリ内に置いている場合に必要です。 jqが Codex から見える PATH にあるか確認してください。 Hook のコマンドは Codex の環境とセッションの作業ディレクトリで実行されます。- 1 日の上限を確認してください。 無料プランでは 1 日 50 件まで送信できます。Stop はターンごとに発生するため、すぐに上限に達することがあります。
FAQ
[tui] notifications はどうですか?
これは Codex 内蔵のターミナル通知です。デフォルトで有効で、ターンの完了と承認要求の両方を扱えますが、通知はパソコン上にターミナル経由で表示されます。プッシュ通知はスマホに届き、履歴も残ります。
Codex の IDE 拡張機能でも使えますか?
拡張機能は、同じ ~/.codex の設定を使ってお使いのマシン上で Codex エージェントを実行します。そのため、まず CLI で hooks を設定して信頼してください。Codex のクラウドタスクは OpenAI のサーバーで動くため、ローカルの hooks は実行されません。
スマホから承認できますか?
このスクリプトでは無理です。Codex が待機中であることを知らせるだけです。PermissionRequest の hook は許可または拒否の結果を返せるので、スマホから呼び出せるエンドポイントを用意すれば、その上に承認の仕組みを作ることもできます。パターンについては人間が介在する通知で紹介しています。
無料で使えますか?
はい。Hooks は Codex に組み込まれており、Pocket Alert の無料プランでは 1 台のデバイスに対して 1 日 50 件まで送信できます。
API キーを取得して hook を追加すれば、ターミナルを確認し続ける必要はなくなります。