Notifications Codex CLI : une notification push quand la tâche est terminée

Codex CLI vous prévient déjà quand il a terminé, à condition que vous regardiez le terminal. Ses notifications intégrées sont des codes d’échappement du terminal : une bannière de bureau si votre terminal les prend en charge, une alerte sonore sinon. Aucune des deux ne vous suit jusqu’à la cuisine.
Codex peut aussi exécuter vos propres commandes à certains moments de son cycle de vie, et c’est tout ce qu’il faut pour une notification push. Ce guide en envoie une quand Codex termine un tour et une autre quand il s’arrête pour demander une approbation.
Deux façons pour Codex d’exécuter votre commande
- Hooks, le mécanisme actuel. Configuré dans
hooks.json, activé par défaut, avec des événements commeStop,PermissionRequest,PreToolUseetSessionEnd. La commande reçoit l’événement au format JSON sur stdin. notify, l’ancien paramètre deconfig.toml. Il se déclenche sur un seul événement,agent-turn-complete, et transmet le JSON comme dernier argument de la ligne de commande. Il fonctionne encore, mais le code source de Codex le marque comme déprécié.
Utilisez les hooks. La version notify figure à la fin pour les configurations plus anciennes.
Ce dont vous avez besoin
- Codex CLI, une version récente avec les hooks.
jqetcurl.- Un compte Pocket Alert, une clé API depuis Clés API, et l’application sur votre téléphone. L’offre gratuite suffit.
Placez la clé API dans un fichier que vous seul pouvez lire, pour qu’elle n’apparaisse ni dans l’historique de votre shell ni dans son environnement :
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
Étape 1. Le script de hook
Enregistrez ceci sous ~/.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 est strict sur la sortie des hooks. Pour Stop, il attend soit rien, soit du JSON sur stdout, et le code de sortie 2 lui demande de continuer au lieu de s’arrêter. C’est pourquoi toute la sortie de curl part dans /dev/null et que le script se termine toujours par exit 0.
Les hooks PermissionRequest peuvent aussi approuver ou refuser à la place de l’utilisateur. Celui-ci ne fait ni l’un ni l’autre : il n’affiche rien, Codex affiche donc son invite d’approbation habituelle, et vous recevez une notification indiquant qu’il attend.
Ou avec la CLI Pocket Alert
Avec la CLI Pocket Alert 2.0 ou ultérieure installée, le bloc curl se réduit à une seule commande. La CLI échappe elle-même le texte et récupère la clé via pocketalert auth, le fichier de clé n’est donc plus nécessaire :
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
Conservez -t et -m plutôt que des arguments positionnels : une réponse commençant par un tiret, comme une liste Markdown, serait sinon lue comme une option.
Étape 2. Enregistrer les hooks
Créez ~/.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 }
]
}
]
}
}
Le fichier dans votre répertoire personnel s’applique partout. Un .codex/hooks.json placé dans un dépôt ne s’applique qu’à ce projet, et seulement une fois le projet marqué comme approuvé.
Les hooks sont activés par défaut. Si vous les avez désactivés à un moment donné, supprimez hooks = false de la table [features] dans ~/.codex/config.toml.
Codex n’exécute que les hooks que vous avez examinés et approuvés. Au prochain démarrage, il signale que les nouveaux hooks doivent être examinés : ouvrez /hooks, vérifiez les deux entrées et approuvez-les. Si vous les modifiez plus tard, Codex les ignore jusqu’à nouvelle approbation.
Étape 3. Tester
Lancez Codex dans un projet quelconque et donnez-lui une tâche courte :
> Summarise README.md in one sentence.
Quand le tour se termine, votre téléphone affiche Codex finished · your-project avec le résumé. Demandez-lui d’exécuter une commande qui nécessite une approbation : une seconde notification, Codex needs approval, arrive avec une priorité élevée.
Pour tester le script sans Codex :
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
| ~/.codex/hooks/pocketalert.sh
Ce qui arrive sur votre téléphone
| Événement | Titre | Contenu | Niveau |
|---|---|---|---|
| Tour terminé | Codex finished · api | 300 premiers caractères de la dernière réponse | default |
| Approbation requise | Codex needs approval · api | Wants to run Bash | high |
high est envoyé comme notification urgente sur iPhone, donc la notification d’approbation passe malgré le mode Concentration, tandis que les notifications « terminé » courantes restent silencieuses. Les deux restent dans l’historique de l’application et dans le tableau de bord web.
La méthode plus ancienne : notify
Si votre version de Codex est antérieure aux hooks, ou si vous utilisez déjà notify, cela fonctionne avec quelques modifications. Codex transmet l’événement comme dernier argument au lieu de stdin, utilise des clés en kebab-case, et ne signale que les tours terminés :
#!/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 n’a pas d’événement d’approbation : utilisez les hooks si vous voulez savoir quand Codex est bloqué.
Ou laissez Codex l’envoyer via MCP
Les hooks se déclenchent sur des événements fixes. Pour laisser Codex décider de ce qu’il vous signale, ajoutez le serveur MCP Pocket Alert dans ~/.codex/config.toml :
[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"
ou en ligne de commande :
codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
--bearer-token-env-var POCKETALERT_API_KEY
Exportez POCKETALERT_API_KEY dans le shell qui lance Codex. Ensuite, une consigne du type « lance la suite de tests et envoie-moi les échecs » se termine par un appel de Codex à create_message avec un résumé qu’il a rédigé. L’outil accepte aussi level et actions.
Si rien n’arrive
- Exécutez la commande de test. Si elle fonctionne là, le problème vient de l’enregistrement des hooks ; sinon, supprimez
>/dev/null 2>&1pour voir l’erreur de curl.401signifie que la clé est incorrecte. - Vérifiez que les hooks sont approuvés. Ouvrez
/hooksdans Codex ; les hooks non approuvés ou modifiés sont ignorés. - Vérifiez que le projet est approuvé si vous avez placé
hooks.jsondans le dépôt. - Vérifiez que
jqest dans le PATH vu par Codex. Les commandes de hook s’exécutent avec l’environnement de Codex et le répertoire de travail de la session. - Vérifiez la limite quotidienne. L’offre gratuite envoie 50 messages par jour, et
Stopse déclenche après chaque tour.
FAQ
Et [tui] notifications ?
C’est la notification terminal intégrée à Codex. Elle est activée par défaut et peut couvrir à la fois les tours terminés et les demandes d’approbation, mais elle s’affiche sur l’ordinateur, dans votre terminal. Une notification push atteint votre téléphone et conserve un historique.
Cela fonctionne-t-il avec l’extension IDE de Codex ?
L’extension exécute l’agent Codex sur votre machine avec la même configuration ~/.codex. Configurez donc et approuvez d’abord les hooks dans la CLI. Les tâches Codex cloud s’exécutent sur les serveurs d’OpenAI et n’exécutent pas vos hooks locaux.
Puis-je approuver depuis le téléphone ?
Pas avec ce script : il indique seulement que Codex attend. Un hook PermissionRequest peut renvoyer une décision d’autorisation ou de refus, vous pouvez donc bâtir des approbations dessus avec un point de terminaison que votre téléphone appelle. Notifications human-in-the-loop montre le schéma.
C’est gratuit ?
Oui. Les hooks sont intégrés à Codex, et l’offre gratuite de Pocket Alert couvre 50 messages par jour sur un appareil.
Obtenez une clé API, ajoutez le hook, et arrêtez de surveiller le terminal.