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

> Receba uma notificação push no celular quando o Claude Code terminar uma tarefa, aguardar permissão ou parar por causa de um erro. Um script de hook, três eventos, sem plugin.

*11.10.2026*

<!-- source: https://pocketalert.app/pt/blog/claude-code-push-notifications -->

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](/account/apikeys). O plano gratuito já basta.
- O aplicativo Pocket Alert no seu [iPhone ou Android](/get-app), 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:

```bash
#!/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:

```bash
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](/tools/cli) 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`:

```bash
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:

```json
{
  "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:

```text
> 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:

```bash
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

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Evento</th><th>Título</th><th>Corpo</th><th>Nível</th></tr></thead>
<tbody>
<tr><th>Tarefa concluída</th><td>Claude finished · api</td><td>Os primeiros 300 caracteres da última resposta do Claude</td><td>default</td></tr>
<tr><th>Pedido de permissão</th><td>Claude needs you · api</td><td>Claude needs your permission</td><td>high</td></tr>
<tr><th>Aguardando entrada</th><td>Claude needs you · api</td><td>Claude is waiting for your input</td><td>high</td></tr>
<tr><th>Erro de API</th><td>Claude stopped · api</td><td>API error: rate_limit</td><td>high</td></tr>
</tbody>
</table>
</div>

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](/messages), 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:

```bash
[ -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](https://info.pocketalert.app/features/action-buttons.html) 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](/tools/mcp):

```bash
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](/blog/human-in-the-loop-notifications).

## 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](/signup), adicione o script e deixe o Claude avisar quando for a sua vez.
