Notificações push no Cursor: um aviso quando o agente terminar

O agente do Cursor pode refatorar um módulo enquanto você faz um café, mas, em uma execução local comum, o Cursor avisa que terminou apenas no computador: com um som ou uma notificação do sistema, se você tiver ativado. O app do Cursor para iOS envia push quando um agente termina uma etapa, mas só para agentes na nuvem e sessões que você transfere com o Remote Control, em um plano pago e com iPhone. O Android está previsto.
Se você quer receber uma notificação push no celular quando uma execução de agente local terminar, o Cursor oferece duas formas de enviar uma:
- Um hook
stop. O Cursor executa seu script sempre que o loop do agente termina, seja por ter concluído, por ter sido abortado ou por ter dado erro. Confiável e igual em todas as vezes. - Uma ferramenta MCP. Adicione o servidor MCP do Pocket Alert e o agente pode enviar uma notificação push sempre que você pedir, com uma mensagem que ele mesmo escreve.
Este guia configura as duas. Cada uma leva alguns minutos.
O que você precisa
- Cursor 1.7 ou mais recente; os hooks chegaram na versão 1.7.
jqecurlpara o hook.- Uma conta no Pocket Alert, uma chave de API em Chaves de API e o app no celular. O plano gratuito é suficiente.
Um Cursor aberto pelo Dock não lê o seu .zshrc, então variáveis de ambiente exportadas ali ficam invisíveis para ele. Guarde a chave em um arquivo:
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
Opção 1. Um hook de stop para cada execução
O script
O Cursor passa ao hook um objeto JSON pela entrada padrão (stdin). Para stop, ele inclui status (completed, aborted ou error) e workspace_roots, as pastas abertas na janela. Salve isto como ~/.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
As execuções abortadas são ignoradas de propósito: se você pressionou parar, já sabe o que aconteceu. O script imprime {} porque um hook stop pode retornar um followup_message, que o Cursor envia de volta ao agente como seu próximo prompt; um objeto vazio significa "nada a acrescentar".
Ou com a CLI do Pocket Alert
Com a CLI do Pocket Alert 2.0 ou mais recente instalada, o bloco do curl se reduz a um comando. A CLI faz o escape do texto sozinha e pega a chave de pocketalert auth:
pocketalert send -t "$title" -m "Agent run $status" -l "$level" -q >/dev/null 2>&1 || true
Mantenha -t e -m em vez de argumentos posicionais: uma resposta que começa com hífen, como uma lista Markdown, seria lida como opção.
Registre o hook
Crie ~/.cursor/hooks.json:
{
"version": 1,
"hooks": {
"stop": [
{ "command": "/Users/you/.cursor/hooks/pocketalert.sh", "timeout": 10 }
]
}
}
Use o caminho absoluto do script; substitua /Users/you pela sua pasta pessoal. O arquivo na sua pasta pessoal vale para todos os projetos. Para um único projeto, coloque-o em .cursor/hooks.json dentro do repositório.
O Cursor recarrega o hooks.json sozinho quando o arquivo muda. Dê ao agente uma tarefa pequena, e o seu celular mostrará Cursor finished · your-project quando ela terminar.
Quer a resposta do agente na notificação?
O stop não inclui a resposta do agente, mas o afterAgentResponse inclui, no campo text. Para enviar as primeiras linhas da resposta em vez de só o status, registre um script do mesmo tipo em afterAgentResponse e leia .text da entrada padrão. Ele dispara após cada resposta, então é mais barulhento; a maioria das pessoas mantém o stop.
Opção 2. O servidor MCP
O hook avisa que uma execução terminou. O servidor MCP permite que o agente diga o que aconteceu. Adicione o Pocket Alert em ~/.cursor/mcp.json:
{
"mcpServers": {
"pocketalert": {
"url": "https://mcp.pocketalert.app/mcp",
"headers": { "Authorization": "Bearer YOUR_API_KEY" }
}
}
}
A chave fica escrita no arquivo por causa do problema do Dock mencionado acima. Este arquivo fica na sua pasta pessoal, não em um repositório. Se você iniciar o Cursor pelo terminal com a chave exportada, "Bearer ${env:POCKETALERT_API_KEY}" funciona no lugar.
Abra a seção MCP das Configurações do Cursor, confira se pocketalert mostra as suas ferramentas e peça:
> Run the test suite. When it's done, push me the number of failures with Pocket Alert.
O agente chama create_message com um resumo que ele mesmo escreveu. Ele também pode definir level, então uma suíte com falhas pode chegar como high, e anexar botões de ação em um plano pago.
Para transformar isso em hábito, em vez de uma instrução por prompt, adicione uma regra de projeto:
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.
Qual usar
| Hook de stop | Ferramenta MCP | |
|---|---|---|
| Dispara | Em toda execução, sempre | Quando o agente decide |
| Mensagem | Status: completed ou error | O que o agente escrever |
| Precisa de | Um script e o hooks.json | Um bloco no mcp.json |
| Pode falhar em silêncio | Só se a rede estiver fora | Se o modelo esquecer |
As duas juntas são um bom padrão: o hook garante que você saiba de cada execução, e a ferramenta MCP entrega o conteúdo quando ele importa.
Aprovações
O Cursor não tem um hook para "o agente está esperando aprovação". beforeShellExecution e preToolUse disparam antes de cada comando, inclusive dos que o Cursor executa sem perguntar, então não conseguem avisar quando você realmente é necessário. As notificações nativas do desktop do Cursor e o app iOS cobrem esse caso hoje.
Se você quer que o agente pare e pergunte antes de uma etapa arriscada, dê a ele a ferramenta MCP e uma regra para enviar um push com botões Aprovar e Recusar; Notificações com humano no circuito mostra como transformar isso em uma trava real, e não em um pedido educado.
Se nada chegar
- Execute o script manualmente:
echo '{"status":"completed","workspace_roots":["/tmp/demo"]}' | ~/.cursor/hooks/pocketalert.sh. Se nenhuma notificação chegar, remova>/dev/null 2>&1para ver o erro do curl. - Reinicie o Cursor se o hook ainda não rodar. Normalmente o Cursor recarrega o
hooks.jsonsozinho quando o arquivo muda. - Confira o caminho no
hooks.json: ele precisa ser absoluto, e o script precisa ser executável. - No caso do MCP, verifique a lista de ferramentas. Um erro ao lado do servidor nas configurações MCP do Cursor geralmente indica que a chave está errada ou vazia.
Perguntas frequentes
O Cursor tem notificações push nativas?
No computador, sim: um som de conclusão e notificações do sistema. No celular, o app do Cursor para iOS envia push quando um agente na nuvem, ou uma sessão que você transfere com o Remote Control, termina uma etapa. Isso exige um plano pago e um iPhone. As execuções locais comuns ficam no computador, e é isso que a configuração aqui cobre.
Isso funciona com agentes em segundo plano e na nuvem?
O hook em ~/.cursor/hooks.json roda apenas na sua máquina, então cobre os agentes executados localmente. Agentes na nuvem rodam nos servidores do Cursor: eles executam os hooks de projeto do .cursor/hooks.json do repositório, mas não os hooks de usuário, e o arquivo com a chave não está lá. Para eles, a rota MCP funciona se o agente tiver o servidor configurado, ou use o app iOS do Cursor ou a integração com o Slack.
O agente vê a minha chave de API?
Na configuração com hook, não: a chave fica em um arquivo que só o script lê. Na configuração MCP, a chave fica na configuração do Cursor e é enviada ao servidor MCP, não ao modelo.
É gratuito?
Sim. Hooks e MCP fazem parte do Cursor, e o plano gratuito do Pocket Alert inclui 50 mensagens por dia em um dispositivo.
Obtenha uma chave de API, adicione o hook e deixe o Cursor avisar quando terminar.