# Notificações do Codex CLI: um push quando a tarefa terminar

> Receba uma notificação push no celular quando o OpenAI Codex CLI terminar uma resposta ou pedir aprovação. Hooks do Codex com o Pocket Alert, e a configuração antiga notify como alternativa.

*14.10.2026*

<!-- source: https://pocketalert.app/pt/blog/codex-notifications -->

O Codex CLI já avisa quando termina, desde que você esteja olhando para o terminal. As notificações nativas dele são códigos de escape do terminal: um banner na área de trabalho, se o seu terminal suportar, ou um sinal sonoro, se não suportar. Nenhuma das duas acompanha você até a cozinha.

O Codex também pode executar seus próprios comandos em momentos do ciclo de vida dele, e isso é tudo que uma notificação push precisa. Este guia envia uma quando o Codex termina uma resposta e outra quando ele para para pedir aprovação.

## Duas formas de o Codex executar seu comando

- **Hooks**, o mecanismo atual. Configurados em `hooks.json`, ativados por padrão, com eventos como `Stop`, `PermissionRequest`, `PreToolUse` e `SessionEnd`. O comando recebe o evento como JSON na entrada padrão (stdin).
- **`notify`**, a configuração mais antiga, em `config.toml`. Ela dispara em um único evento, `agent-turn-complete`, e passa o JSON como último argumento da linha de comando. Continua funcionando, mas o código-fonte do Codex a marca como legada.

Use hooks. A versão com `notify` fica no final, para configurações mais antigas.

## O que você precisa

- Codex CLI, em uma versão recente com suporte a hooks.
- `jq` e `curl`.
- Uma conta no Pocket Alert, uma chave de API em [Chaves de API](/account/apikeys) e o [aplicativo](/get-app) no seu celular. O plano gratuito é suficiente.

Guarde a chave de API em um arquivo que só você consegue ler, assim ela não fica no histórico do shell nem no ambiente:

```bash
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
```

## Passo 1. O script do hook

Salve este conteúdo em `~/.codex/hooks/pocketalert.sh`:

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

case "$(jq -r '.hook_event_name' <<<"$payload")" in
  Stop)
    title="Codex finished · $project"
    message=$(jq -r '.last_assistant_message // "Turn complete"' <<<"$payload")
    level=default ;;
  PermissionRequest)
    title="Codex needs approval · $project"
    message=$(jq -r '"Wants to run " + (.tool_name // "a tool")' <<<"$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: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true

exit 0
```

```bash
chmod +x ~/.codex/hooks/pocketalert.sh
```

O Codex é rigoroso com a saída dos hooks. Para `Stop`, ele espera nada ou JSON na saída padrão, e o código de saída 2 faz com que ele continue em vez de parar. Por isso, toda a saída do curl vai para `/dev/null` e o script sempre termina com `exit 0`.

Hooks de `PermissionRequest` também podem aprovar ou negar em nome do Codex. Este não faz nenhuma das duas coisas: não imprime nada, então o Codex mostra o pedido de aprovação normal e você recebe um push avisando que ele está esperando.

### Ou com o CLI do Pocket Alert

Com o [CLI do Pocket Alert](/tools/cli) 2.0 ou mais recente instalado, o bloco do curl se reduz a um comando. O CLI faz o escape do texto sozinho e pega a chave com `pocketalert auth`, então o arquivo de chave não é mais necessário:

```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 em Markdown, seria interpretada como opção.

## Passo 2. Registrar os hooks

Crie `~/.codex/hooks.json`:

```json
{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "hooks": [
          { "type": "command", "command": "~/.codex/hooks/pocketalert.sh", "timeout": 30 }
        ]
      }
    ]
  }
}
```

O arquivo no seu diretório pessoal vale em todos os lugares. Um `.codex/hooks.json` dentro de um repositório vale apenas para aquele projeto, e só depois que você marcar o projeto como confiável.

Os hooks já vêm ativados. Se você os desativou em algum momento, remova `hooks = false` da tabela `[features]` em `~/.codex/config.toml`.

O Codex executa apenas hooks que você revisou e marcou como confiáveis. Na próxima vez que ele iniciar, vai avisar que novos hooks precisam de revisão: abra `/hooks`, confira as duas entradas e confie nelas. Se você alterá-las depois, o Codex as ignora até que você confie novamente.

## Passo 3. Testar

Inicie o Codex em qualquer projeto e dê uma tarefa curta:

```text
> Summarise README.md in one sentence.
```

Quando a resposta terminar, seu celular mostra **Codex finished · seu-projeto** com o resumo. Peça para ele executar um comando que precise de aprovação, e um segundo push, **Codex needs approval**, chega com prioridade alta.

Para testar o script sem o Codex:

```bash
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
  | ~/.codex/hooks/pocketalert.sh
```

## O que chega no seu 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>Resposta finalizada</th><td>Codex finished · api</td><td>Os primeiros 300 caracteres da última resposta</td><td>default</td></tr>
<tr><th>Aprovação necessária</th><td>Codex needs approval · api</td><td>Wants to run Bash</td><td>high</td></tr>
</tbody>
</table>
</div>

`high` é entregue como sensível ao tempo no iPhone, então o push de aprovação passa pelo Foco enquanto os pushes rotineiros de "finalizado" ficam silenciosos. Ambos permanecem no histórico do aplicativo e no painel web.

## O jeito antigo: notify

Se a sua versão do Codex é anterior aos hooks, ou se você já usa `notify`, ela funciona com algumas mudanças. O Codex passa o evento como último argumento, em vez de stdin, usa chaves em kebab-case e informa apenas respostas finalizadas:

```bash
#!/usr/bin/env bash
event="${@: -1}"
[ "$(jq -r '.type' <<<"$event")" = "agent-turn-complete" ] || exit 0

jq -n --arg m "$(jq -r '."last-assistant-message" // "Turn complete"' <<<"$event" | cut -c1-300)" \
  '{title: "Codex finished", message: $m}' |
  curl -sS --max-time 10 https://api.pocketalert.app/v1/messages \
    -H "Token: $(cat ~/.config/pocketalert/key)" \
    -H 'Content-Type: application/json' \
    --data-binary @- >/dev/null 2>&1 || true
```

```toml
# ~/.codex/config.toml
notify = ["/Users/you/.codex/notify-pocketalert.sh"]
```

O `notify` não tem evento de aprovação, então use hooks se quiser saber quando o Codex está bloqueado.

## Ou deixe o Codex enviar pelo MCP

Os hooks disparam em eventos fixos. Para deixar o Codex decidir o que avisar, adicione o [servidor MCP do Pocket Alert](/tools/mcp) em `~/.codex/config.toml`:

```toml
[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"
```

ou pela linha de comando:

```bash
codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
  --bearer-token-env-var POCKETALERT_API_KEY
```

Exporte `POCKETALERT_API_KEY` no shell que inicia o Codex. Depois, um pedido como "rode a suíte de testes e me mande as falhas" termina com o Codex chamando `create_message` com um resumo que ele mesmo escreveu. A ferramenta também aceita `level` e `actions`.

## Se nada chegar

- **Execute o comando de teste.** Se funcionar ali, o problema está no registro dos hooks; se não funcionar, remova `>/dev/null 2>&1` para ver o erro do curl. `401` significa que a chave está errada.
- **Confira se os hooks são confiáveis.** Abra `/hooks` no Codex; hooks não confiáveis ou alterados são ignorados.
- **Confira se o projeto é confiável** caso você tenha colocado `hooks.json` no repositório.
- **Confira se o `jq` está no PATH** que o Codex enxerga. Os comandos dos hooks rodam com o ambiente do Codex e no diretório de trabalho da sessão.
- **Confira o limite diário.** O plano gratuito envia 50 mensagens por dia, e o Stop dispara após cada resposta.

## Perguntas frequentes

### E o `[tui] notifications`?

É a notificação de terminal nativa do Codex. Ela vem ativada por padrão e pode cobrir tanto respostas finalizadas quanto pedidos de aprovação, mas aparece no computador, pelo terminal. Um push chega ao seu celular e mantém um histórico.

### Isso funciona na extensão do Codex para IDE?

A extensão executa o agente do Codex na sua máquina com a mesma configuração em `~/.codex`, então configure e confie nos hooks primeiro pelo CLI. As tarefas na nuvem do Codex rodam nos servidores da OpenAI e não executam seus hooks locais.

### Dá para aprovar pelo celular?

Não com este script: ele apenas avisa que o Codex está esperando. Um hook `PermissionRequest` pode retornar uma decisão de permitir ou negar, então você pode construir aprovações em cima dele com um endpoint que o seu celular chama. [Notificações com humano no circuito](/blog/human-in-the-loop-notifications) mostra o padrão.

### É grátis?

Sim. Os hooks são nativos do Codex, e o plano gratuito do Pocket Alert cobre 50 mensagens por dia em um dispositivo.

[Obtenha uma chave de API](/signup), adicione o hook e pare de ficar olhando o terminal.
