Voltar para o blog

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

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

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 e o aplicativo 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:

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:

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

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:

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

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

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

O que chega no seu celular

EventoTítuloCorpoNível
Resposta finalizadaCodex finished · apiOs primeiros 300 caracteres da última respostadefault
Aprovação necessáriaCodex needs approval · apiWants to run Bashhigh

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:

#!/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
# ~/.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 em ~/.codex/config.toml:

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

ou pela linha de comando:

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 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, adicione o hook e pare de ficar olhando o terminal.

Compartilhe este artigo