Notifikasi Codex CLI: push notification saat tugas selesai

Codex CLI sudah memberi tahu Anda saat selesai, selama Anda sedang memantau terminal. Notifikasi bawaannya berupa kode escape terminal: banner desktop jika terminal Anda mendukungnya, atau bel jika tidak. Keduanya tidak ikut ke dapur bersama Anda.
Codex juga dapat menjalankan perintah Anda sendiri pada titik-titik tertentu dalam siklus hidupnya, dan itulah yang dibutuhkan push notification ke ponsel. Panduan ini mengirim satu push saat Codex selesai menjalankan satu giliran dan push lain saat ia berhenti untuk meminta persetujuan.
Dua cara Codex menjalankan perintah Anda
- Hooks, mekanisme terkini. Dikonfigurasi di
hooks.json, aktif secara default, dengan event sepertiStop,PermissionRequest,PreToolUse, danSessionEnd. Perintah menerima event dalam bentuk JSON melalui stdin. notify, pengaturan lama diconfig.toml. Ia dipicu oleh satu event,agent-turn-complete, dan meneruskan JSON sebagai argumen baris perintah terakhir. Masih berfungsi, tetapi sumber Codex menandainya sebagai legacy.
Gunakan hooks. Versi notify ada di bagian akhir untuk pengaturan lama.
Yang Anda butuhkan
- Codex CLI, rilis terbaru yang sudah mendukung hooks.
jqdancurl.- Akun Pocket Alert, kunci API dari Kunci API, dan aplikasi di ponsel Anda. Paket gratis sudah cukup.
Simpan kunci API di berkas yang hanya bisa dibaca oleh Anda, agar tidak tercatat di riwayat shell atau environment:
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
Langkah 1. Skrip hook
Simpan ini sebagai ~/.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 sangat ketat soal output hook. Untuk Stop, ia mengharapkan tidak ada output atau JSON di stdout, dan kode keluar 2 memberi tahu Codex untuk melanjutkan alih-alih berhenti. Itulah sebabnya seluruh output curl diarahkan ke /dev/null dan skrip selalu diakhiri dengan exit 0.
Hook PermissionRequest juga bisa menyetujui atau menolak atas nama Codex. Skrip ini tidak melakukan keduanya: ia tidak mencetak apa pun, sehingga Codex menampilkan prompt persetujuan biasanya dan Anda mendapat push yang memberi tahu bahwa Codex sedang menunggu.
Atau dengan CLI Pocket Alert
Jika CLI Pocket Alert versi 2.0 atau lebih baru sudah terpasang, blok curl menyusut menjadi satu perintah. CLI sendiri yang meng-escape teks dan mengambil kunci dari pocketalert auth, sehingga berkas kunci tidak lagi diperlukan:
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
Gunakan -t dan -m, bukan argumen posisional: balasan yang diawali tanda hubung, seperti daftar Markdown, bisa terbaca sebagai opsi.
Langkah 2. Daftarkan hooks
Buat ~/.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 }
]
}
]
}
}
Berkas di direktori home Anda berlaku di mana pun. .codex/hooks.json di dalam repositori berlaku untuk proyek tersebut, tetapi hanya setelah Anda menandai proyek sebagai tepercaya.
Hooks aktif secara default. Jika sebelumnya Anda mematikannya, hapus hooks = false dari tabel [features] di ~/.codex/config.toml.
Codex hanya menjalankan hook yang sudah Anda tinjau dan percayai. Saat pertama kali dijalankan lagi, ia akan memperingatkan bahwa hook baru perlu ditinjau: buka /hooks, periksa kedua entri, dan percayai keduanya. Jika Anda mengubahnya nanti, Codex akan melewatinya sampai Anda mempercayainya lagi.
Langkah 3. Uji coba
Jalankan Codex di proyek mana pun dan berikan tugas singkat:
> Summarise README.md in one sentence.
Saat giliran berakhir, ponsel Anda menampilkan Codex finished · your-project beserta ringkasannya. Mintalah Codex menjalankan perintah yang membutuhkan persetujuan, dan push kedua, Codex needs approval, akan masuk dengan prioritas tinggi.
Untuk menguji skrip tanpa Codex:
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
| ~/.codex/hooks/pocketalert.sh
Apa yang masuk ke ponsel Anda
| Event | Judul | Isi | Level |
|---|---|---|---|
| Giliran selesai | Codex finished · api | 300 karakter pertama dari balasan terakhir | default |
| Perlu persetujuan | Codex needs approval · api | Wants to run Bash | high |
high dikirim sebagai time-sensitive di iPhone, sehingga push persetujuan tetap lolos dari Fokus, sementara push "finished" rutin tetap senyap. Keduanya tersimpan di riwayat aplikasi dan dasbor web.
Cara lama: notify
Jika versi Codex Anda lebih lama dari hooks, atau Anda sudah memakai notify, cara ini tetap berfungsi dengan sedikit perubahan. Codex meneruskan event sebagai argumen terakhir alih-alih stdin, memakai kunci dengan format kebab-case, dan hanya melaporkan giliran yang selesai:
#!/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 tidak memiliki event persetujuan, jadi gunakan hooks jika Anda ingin tahu saat Codex terhenti menunggu.
Atau biarkan Codex mengirimnya lewat MCP
Hooks dipicu oleh event yang tetap. Agar Codex yang memutuskan apa yang perlu diberitahukan, tambahkan server MCP Pocket Alert ke ~/.codex/config.toml:
[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"
atau dari baris perintah:
codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
--bearer-token-env-var POCKETALERT_API_KEY
Ekspor POCKETALERT_API_KEY di shell yang menjalankan Codex. Lalu prompt seperti "jalankan test suite dan kirim saya kegagalannya" akan diakhiri dengan Codex memanggil create_message dengan ringkasan yang ia tulis sendiri. Tool tersebut juga menerima level dan actions.
Jika tidak ada yang masuk
- Jalankan perintah uji. Jika berhasil di sana, masalahnya ada di pendaftaran hook; jika tidak, hapus
>/dev/null 2>&1untuk melihat error dari curl.401berarti kuncinya salah. - Periksa hook sudah tepercaya. Buka
/hooksdi Codex; hook yang belum tepercaya atau sudah berubah akan dilewati. - Periksa proyek sudah tepercaya jika Anda menaruh
hooks.jsondi dalam repositori. - Periksa
jqada di PATH yang dilihat Codex. Perintah hook berjalan dengan environment Codex dan direktori kerja sesi. - Periksa batas harian. Paket gratis mengirim 50 pesan per hari, dan Stop aktif setelah setiap giliran.
FAQ
Bagaimana dengan [tui] notifications?
Itu adalah notifikasi terminal bawaan Codex. Fitur ini aktif secara default dan bisa mencakup giliran selesai maupun permintaan persetujuan, tetapi notifikasinya muncul di komputer, lewat terminal Anda. Push sampai ke ponsel dan tetap tersimpan sebagai riwayat.
Apakah ini berfungsi di ekstensi IDE Codex?
Ekstensi menjalankan agen Codex di mesin Anda dengan konfigurasi ~/.codex yang sama, jadi atur dan percayai hooks di CLI terlebih dahulu. Tugas cloud Codex berjalan di server OpenAI dan tidak menjalankan hooks lokal Anda.
Bisakah saya menyetujui dari ponsel?
Tidak dengan skrip ini: ia hanya memberi tahu bahwa Codex sedang menunggu. Hook PermissionRequest dapat mengembalikan keputusan izinkan atau tolak, sehingga Anda bisa membangun fitur persetujuan di atasnya dengan endpoint yang dipanggil ponsel Anda. Notifikasi human-in-the-loop menjelaskan polanya.
Apakah ini gratis?
Ya. Hooks sudah terpasang di Codex, dan paket Gratis Pocket Alert mencakup 50 pesan per hari di satu perangkat.
Dapatkan kunci API, pasang hook, dan berhenti memantau terminal.