Voltar para o blog

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

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.
  • jq e curl para 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 stopFerramenta MCP
DisparaEm toda execução, sempreQuando o agente decide
MensagemStatus: completed ou errorO que o agente escrever
Precisa deUm script e o hooks.jsonUm bloco no mcp.json
Pode falhar em silêncioSó se a rede estiver foraSe 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>&1 para ver o erro do curl.
  • Reinicie o Cursor se o hook ainda não rodar. Normalmente o Cursor recarrega o hooks.json sozinho 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.

Compartilhe este artigo