Voltar para o blog

Notificações push para Claude Code: saiba quando uma tarefa termina

Notificações push para Claude Code: saiba quando uma tarefa termina

O Claude Code consegue trabalhar sozinho por vinte minutos sem problema. O problema está no que acontece depois desses vinte minutos: ou você fica olhando o terminal, ou se afasta e volta para descobrir que ele está esperando uma confirmação de permissão desde o minuto três.

Os hooks resolvem os dois casos. O Claude Code executa um comando de shell em pontos fixos do seu ciclo de vida, e três desses pontos são exatamente o que você quer no celular:

  • Stop: o Claude terminou de responder. A tarefa acabou ou ele tem uma pergunta.
  • Notification: o Claude precisa de você. Um pedido de permissão ou ele ficou ocioso esperando uma entrada.
  • StopFailure: a resposta foi interrompida por um erro de API, como limite de requisições ou um problema de cobrança.

Este guia conecta os três ao Pocket Alert com um único script. A configuração leva cerca de cinco minutos.

O que você precisa

  • Claude Code, em qualquer versão recente.
  • jq e curl. Os dois vêm na maioria das distribuições Linux; no macOS, use brew install jq.
  • Uma conta no Pocket Alert e uma chave de API em Chaves de API. O plano gratuito já basta.
  • O aplicativo Pocket Alert no seu iPhone ou Android, com você conectado.

Passo 1. O script do hook

O Claude Code envia para cada hook um objeto JSON pela entrada padrão (stdin). Os campos que você precisa são hook_event_name, cwd, last_assistant_message no Stop, message no Notification e error no StopFailure. O script transforma isso em uma notificação push:

#!/usr/bin/env bash
payload=$(cat)
project=$(basename "$(jq -r '.cwd' <<<"$payload")")

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Claude finished · $project"
    message=$(jq -r '.last_assistant_message // "Task complete"' <<<"$payload")
    level=default ;;
  Notification)
    title="Claude needs you · $project"
    message=$(jq -r '.message' <<<"$payload")
    level=high ;;
  StopFailure)
    title="Claude stopped · $project"
    message=$(jq -r '"API error: " + (.error // "unknown")' <<<"$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: $POCKETALERT_API_KEY" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null || true

exit 0

Salve como ~/.claude/hooks/pocketalert.sh e torne-o executável:

mkdir -p ~/.claude/hooks
chmod +x ~/.claude/hooks/pocketalert.sh

Duas partes do script importam mais do que parecem:

  • jq -n monta o JSON. A última mensagem do Claude está cheia de aspas, crases e quebras de linha. Colá-la manualmente em uma string JSON quebra na primeira aspas; o jq faz o escape corretamente.
  • exit 0 no final e || true depois do curl. Em um hook de Stop, o código de saída 2 significa "não pare, continue". Um hook de notificação nunca pode bloquear o Claude, mesmo quando sua rede estiver fora.

Ou com a CLI do Pocket Alert

Com a CLI do Pocket Alert 2.0 ou mais recente instalada, o bloco do curl vira um único comando. A CLI faz o escape do texto sozinha e pega a chave de POCKETALERT_API_KEY (o bloco env abaixo a define) ou de pocketalert auth:

pocketalert send -t "$title" -m "${message:0:300}" -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.

Passo 2. Registre os hooks

Adicione os hooks em ~/.claude/settings.json para que valham para todos os projetos. Se o arquivo já tiver uma chave hooks, mescle estas entradas nela:

{
  "env": {
    "POCKETALERT_API_KEY": "YOUR_API_KEY"
  },
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
    ],
    "StopFailure": [
      { "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }] }
    ],
    "Notification": [
      {
        "matcher": "permission_prompt|idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/pocketalert.sh" }]
      }
    ]
  }
}

O bloco env entrega a chave de API ao hook sem colocá-la no seu perfil do shell. Se você já exporta POCKETALERT_API_KEY em outro lugar, deixe o bloco de fora.

O matcher em Notification filtra pelo tipo de notificação. permission_prompt dispara quando um pedido de permissão ficou cerca de seis segundos sem resposta, e idle_prompt cerca de um minuto depois que o Claude termina, se você não tiver digitado nada desde então. Em uma sessão de terminal, os dois só disparam quando você parece estar longe dele, então não vibram no celular enquanto você está acompanhando. O Stop não tem matcher: ele dispara toda vez que o Claude termina uma resposta.

Para limitar os hooks a um único repositório, coloque o mesmo bloco hooks em .claude/settings.json dentro desse repositório, ou em .claude/settings.local.json para mantê-lo fora do git.

Passo 3. Teste

O Claude Code normalmente percebe sozinho as edições no arquivo de configurações (inicie uma nova sessão se /hooks ainda não listar os hooks). Peça algo simples:

> List the files in this directory and stop.

Quando o Claude terminar, o celular mostra Claude finished · your-project com o início da resposta. Se nada chegar, execute /hooks dentro do Claude Code para ver os hooks registrados.

Para testar o script isoladamente, envie um evento falso:

echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | POCKETALERT_API_KEY=YOUR_API_KEY ~/.claude/hooks/pocketalert.sh

O que chega no celular

EventoTítuloCorpoNível
Tarefa concluídaClaude finished · apiOs primeiros 300 caracteres da última resposta do Claudedefault
Pedido de permissãoClaude needs you · apiClaude needs your permissionhigh
Aguardando entradaClaude needs you · apiClaude is waiting for your inputhigh
Erro de APIClaude stopped · apiAPI error: rate_limithigh

O nível high chega como sensível ao tempo no iPhone, então um pedido de permissão atravessa o Foco, enquanto as mensagens rotineiras de "concluído" continuam silenciosas. Todo push também fica no histórico do aplicativo e no painel web, para que você possa rolar de volta e ver o que o Claude fez durante a noite.

Adapte ao seu jeito

Só quando você estiver longe. O Stop dispara depois de cada resposta, inclusive as rápidas que você está acompanhando. Adicione um interruptor no topo do script:

[ -f ~/.claude/away ] || exit 0

Depois, execute touch ~/.claude/away ao sair da mesa e rm ~/.claude/away ao voltar. Pedidos de permissão valem a pena de qualquer forma, então você pode colocar a verificação apenas dentro do ramo Stop).

Agrupe por projeto. Crie um aplicativo por projeto no Pocket Alert e adicione application_id ao JSON. Assim o app filtra por projeto, e você pode definir um nível padrão para cada um.

Não bloqueie o Claude de jeito nenhum. Adicione "async": true ao lado de "type": "command" e o hook roda em segundo plano. Evite isso em execuções sem interface (claude -p): hooks em segundo plano são encerrados quando a sessão termina, e o push pode nunca sair.

Retome pelo celular. Em um plano pago, um botão de ação do tipo copy com o ID da sessão permite copiar claude --resume <id> pelo celular e colar quando você voltar.

Ou deixe o Claude enviar pelo MCP

Os hooks são determinísticos: disparam, lembre-se disso o Claude ou não. A outra opção é dar ao Claude uma ferramenta de notificação e deixar que ele decida quando usá-la. Adicione o servidor MCP do Pocket Alert:

claude mcp add --transport http pocketalert https://mcp.pocketalert.app/mcp \
  --scope user --header "Authorization: Bearer YOUR_API_KEY"

Agora você pode dizer "rode a migração e me envie a contagem de linhas quando terminar", e o Claude chama create_message com uma mensagem que ele mesmo escreve para a ocasião. A ferramenta também aceita level e actions, e list_messages permite que o Claude consulte o que enviou antes.

Use os dois: hooks para o "concluído" e o "precisa de você" garantidos, MCP para mensagens com conteúdo real. Para aprovações antes de etapas arriscadas, veja Notificações com humano no circuito.

Se nada chegar

  • Confira a chave. Execute o comando de teste acima. Um 401 do curl significa que a chave de API está errada; remova >/dev/null para ver a resposta.
  • Confira se os hooks foram carregados. Execute /hooks. Edições no arquivo de configurações normalmente são percebidas em poucos segundos; se os hooks não aparecerem, reinicie o Claude Code.
  • Confira se o jq está no PATH que o Claude Code usa. Os hooks rodam com o ambiente do Claude, e um editor iniciado pela interface gráfica pode não enxergar /opt/homebrew/bin do Homebrew.
  • Confira o limite diário. O plano gratuito envia 50 mensagens por dia. Uma sessão longa com muitas respostas curtas pode esgotar esse limite; o interruptor de ausência acima ajuda.

Perguntas frequentes

Isso funciona nas extensões do VS Code e do JetBrains?

Sim. As extensões executam o Claude Code por baixo e leem o mesmo ~/.claude/settings.json, então os hooks disparam ali também.

O Claude consegue ver a chave de API?

Não na conversa: os hooks rodam fora dela, e a saída deles para Stop e Notification não é mostrada ao modelo. Mas o bloco env vale para a sessão inteira, então um comando Bash que o Claude execute poderia ler a variável. Se isso importar, guarde a chave em um arquivo que só você consiga ler, como ~/.config/pocketalert/key com permissão 600, e use -H "Token: $(cat ~/.config/pocketalert/key)" no script.

Qual a diferença para o sinal sonoro do terminal?

O sinal sonoro e as notificações da área de trabalho exigem que você esteja diante do computador. Um push chega ao celular onde quer que você esteja, mantém um histórico e pode ser configurado para atravessar o Foco nos pedidos que bloqueiam o Claude.

Consigo receber a resposta inteira, e não só 300 caracteres?

Um push comporta até cerca de 3.000 caracteres de texto. Aumente o limite 0:300, mas lembre que o push serve para decidir se você volta para a mesa, não para ler a resposta completa.

É gratuito?

Sim. Os hooks fazem parte do Claude Code, e o plano gratuito do Pocket Alert cobre 50 mensagens por dia em um dispositivo. Os planos pagos acrescentam mais mensagens, dispositivos e botões de ação.

Crie uma chave de API, adicione o script e deixe o Claude avisar quando for a sua vez.

Compartilhe este artigo