Notifications push Cursor : une alerte quand l’agent a terminé

L’agent de Cursor peut refactoriser un module pendant que vous préparez un café, mais pour une exécution locale ordinaire, Cursor ne vous signale la fin qu’sur l’ordinateur : un son, ou une notification système si vous les avez activés. L’application iOS de Cursor envoie une notification push quand un agent termine un tour, mais seulement pour les agents cloud et les sessions que vous transférez avec Remote Control, avec une offre payante et un iPhone. La prise en charge d’Android est prévue.
Si vous voulez recevoir une notification push sur votre téléphone à la fin d’une exécution locale, Cursor vous propose deux moyens d’en envoyer une :
- Un hook
stop. Cursor exécute votre script à chaque fin de la boucle de l’agent, qu’elle se termine normalement, soit interrompue, soit en erreur. Fiable, identique à chaque fois. - Un outil MCP. Ajoutez le serveur MCP Pocket Alert, et l’agent peut vous envoyer une notification push chaque fois que vous le lui demandez, avec un message qu’il rédige.
Ce guide configure les deux. Chacune prend quelques minutes.
Prérequis
- Cursor 1.7 ou ultérieur ; les hooks sont apparus dans la version 1.7.
jqetcurlpour le hook.- Un compte Pocket Alert, une clé API depuis Clés API, et l’application mobile sur votre téléphone. L’offre gratuite suffit.
Cursor lancé depuis le Dock ne lit pas votre .zshrc : les variables d’environnement exportées là-bas ne lui sont donc pas accessibles. Conservez plutôt la clé dans un fichier :
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
Option 1. Un hook stop pour chaque exécution
Le script
Cursor transmet au hook un objet JSON sur l’entrée standard. Pour stop, il contient status (completed, aborted ou error) et workspace_roots, les dossiers ouverts dans la fenêtre. Enregistrez ce script dans ~/.cursor/hooks/pocketalert.sh :
#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.workspace_roots[0] // "cursor"' <<<"$payload")")
status=$(jq -r '.status // "completed"' <<<"$payload")
case "$status" in
completed) title="Cursor finished · $project"; level=default ;;
error) title="Cursor hit an error · $project"; level=high ;;
*) echo '{}'; exit 0 ;;
esac
jq -n --arg t "$title" --arg m "Agent run $status" --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 ~/.cursor/hooks/pocketalert.sh
Les exécutions interrompues sont volontairement ignorées : si vous avez appuyé sur stop, vous le savez déjà. Le script affiche {} parce qu’un hook stop peut renvoyer un followup_message que Cursor transmet à l’agent comme votre prochain message ; un objet vide signifie « rien à ajouter ».
Ou avec la CLI Pocket Alert
Si vous avez installé la CLI Pocket Alert 2.0 ou ultérieure, 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 :
pocketalert send -t "$title" -m "Agent run $status" -l "$level" -q >/dev/null 2>&1 || true
Conservez -t et -m plutôt que des arguments positionnels : une réponse qui commence par un tiret, comme une liste Markdown, serait sinon lue comme une option.
L’enregistrer
Créez ~/.cursor/hooks.json :
{
"version": 1,
"hooks": {
"stop": [
{ "command": "/Users/you/.cursor/hooks/pocketalert.sh", "timeout": 10 }
]
}
}
Utilisez le chemin absolu du script ; remplacez /Users/you par votre dossier personnel. Le fichier placé dans votre dossier personnel s’applique à tous les projets. Pour un seul projet, placez-le dans .cursor/hooks.json à la racine du dépôt.
Cursor recharge hooks.json automatiquement quand le fichier change. Donnez à l’agent une petite tâche, et votre téléphone affiche Cursor finished · votre-projet à la fin.
Vous voulez la réponse de l’agent dans la notification ?
stop n’inclut pas la réponse de l’agent, mais afterAgentResponse la fournit dans text. Pour envoyer les premières lignes de la réponse au lieu du seul statut, enregistrez un script similaire sur afterAgentResponse et lisez .text depuis l’entrée standard. Il se déclenche après chaque réponse, donc il est plus bruyant ; la plupart des gens conservent stop.
Option 2. Le serveur MCP
Le hook vous indique qu’une exécution s’est terminée. Le serveur MCP permet à l’agent de vous dire ce qui s’est passé. Ajoutez Pocket Alert dans ~/.cursor/mcp.json :
{
"mcpServers": {
"pocketalert": {
"url": "https://mcp.pocketalert.app/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
La clé est écrite dans le fichier à cause du problème du Dock évoqué plus haut. Ce fichier se trouve dans votre dossier personnel, pas dans un dépôt. Si vous lancez Cursor depuis un terminal où la clé est exportée, "Bearer ${env:POCKETALERT_API_KEY}" fonctionne à la place.
Ouvrez la section MCP des paramètres de Cursor, vérifiez que pocketalert affiche ses outils, puis demandez :
> Run the test suite. When it's done, push me the number of failures with Pocket Alert.
L’agent appelle create_message avec un résumé qu’il a rédigé. Il peut aussi définir level, ainsi une suite en échec peut arriver avec high, et joindre des boutons d’action sur une offre payante.
Pour en faire une habitude plutôt qu’une consigne à chaque message, ajoutez une règle de projet :
When a task takes more than a few minutes, finish by calling the pocketalert
create_message tool with a one-line summary. Use level "high" if anything failed.
Quelle solution choisir
| Hook stop | Outil MCP | |
|---|---|---|
| Déclenchement | Chaque exécution, toujours | Quand l’agent le décide |
| Message | Statut : completed ou error | Ce que l’agent rédige |
| Nécessite | Un script et hooks.json | Un bloc dans mcp.json |
| Peut échouer en silence | Seulement si le réseau est coupé | Si le modèle oublie |
Les deux ensemble constituent un bon choix par défaut : le hook garantit que vous êtes prévenu de chaque exécution, l’outil MCP fournit le contenu quand il compte.
Validations
Cursor ne propose pas de hook pour « l’agent attend une validation ». beforeShellExecution et preToolUse se déclenchent avant chaque commande, y compris celles que Cursor exécute sans demander, donc ils ne peuvent pas signaler quand votre intervention est réellement nécessaire. Les notifications de bureau de Cursor et son application iOS couvrent ce cas aujourd’hui.
Si vous voulez que l’agent s’arrête et demande avant une étape risquée, donnez-lui l’outil MCP et une règle pour envoyer une notification push avec les boutons d’action Approuver et Refuser ; Notifications avec validation humaine montre comment en faire un véritable point de contrôle plutôt qu’une simple demande polie.
Si rien n’arrive
- Lancez le script à la main :
echo '{"status":"completed","workspace_roots":["/tmp/demo"]}' | ~/.cursor/hooks/pocketalert.sh. Si aucune notification n’arrive, retirez>/dev/null 2>&1pour voir l’erreur de curl. - Redémarrez Cursor si le hook ne s’exécute toujours pas. Cursor recharge normalement
hooks.jsontout seul quand le fichier change. - Vérifiez le chemin dans
hooks.json: il doit être absolu, et le script doit être exécutable. - Pour MCP, vérifiez la liste des outils. Une erreur affichée à côté du serveur dans les paramètres MCP de Cursor signifie généralement que la clé est fausse ou vide.
FAQ
Cursor propose-t-il des notifications push intégrées ?
Sur l’ordinateur, oui : un son de fin et des notifications système. Sur le téléphone, l’application iOS de Cursor envoie une notification push quand un agent cloud, ou une session transférée avec Remote Control, termine un tour. Il faut une offre payante et un iPhone. Les exécutions locales ordinaires restent sur l’ordinateur, et c’est ce que couvre la configuration présentée ici.
Cela fonctionne-t-il pour les agents en arrière-plan et les agents cloud ?
Le hook défini dans ~/.cursor/hooks.json ne s’exécute que sur votre machine, il couvre donc les agents locaux. Les agents cloud tournent sur les serveurs de Cursor : ils exécutent les hooks de projet du fichier .cursor/hooks.json du dépôt, mais pas les hooks utilisateur, et le fichier de clé n’y est pas présent. Pour eux, la voie MCP fonctionne si le serveur est configuré pour l’agent, ou utilisez l’application iOS de Cursor ou l’intégration Slack.
L’agent voit-il ma clé API ?
Dans la configuration par hook, non : la clé reste dans un fichier que seul le script lit. Dans la configuration MCP, la clé se trouve dans la configuration de Cursor et est envoyée au serveur MCP, et non au modèle.
Est-ce gratuit ?
Oui. Les hooks et MCP font partie de Cursor, et l’offre gratuite de Pocket Alert couvre 50 messages par jour sur un appareil.
Obtenez une clé API, ajoutez le hook, et laissez Cursor vous prévenir quand il a terminé.