Notificaciones push para Codex CLI: un aviso en el teléfono al terminar la tarea

Codex CLI ya te avisa cuando termina, siempre que estés mirando la terminal. Sus notificaciones integradas son códigos de escape de terminal: un banner de escritorio si tu terminal los soporta, y un pitido si no. Ninguna te sigue a la cocina.
Codex también puede ejecutar tus propios comandos en determinados puntos de su ciclo de vida, y eso es todo lo que necesita una notificación push en el teléfono. Esta guía envía una cuando Codex termina un turno y otra cuando se detiene para pedir aprobación.
Dos formas en que Codex ejecuta tu comando
- Hooks, el mecanismo actual. Se configuran en
hooks.json, están activados por defecto y tienen eventos comoStop,PermissionRequest,PreToolUseySessionEnd. El comando recibe el evento como JSON por stdin. notify, la configuración antigua enconfig.toml. Se activa con un solo evento,agent-turn-complete, y pasa el JSON como último argumento de la línea de comandos. Sigue funcionando, pero el código fuente de Codex lo marca como heredado.
Usa hooks. La versión con notify está al final, para configuraciones antiguas.
Qué necesitas
- Codex CLI, una versión reciente con hooks.
jqycurl.- Una cuenta de Pocket Alert, una clave de API desde API Keys y la app en tu teléfono. El plan gratuito es suficiente.
Guarda la clave de API en un archivo que solo tú puedas leer, así no quedará en el historial de la shell ni en el entorno:
mkdir -p ~/.config/pocketalert
printf '%s' 'YOUR_API_KEY' > ~/.config/pocketalert/key
chmod 600 ~/.config/pocketalert/key
Paso 1. El script del hook
Guárdalo como ~/.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
Codex es estricto con la salida de los hooks. En Stop, espera no recibir nada o recibir JSON por stdout, y el código de salida 2 le indica que siga trabajando en lugar de detenerse. Por eso toda la salida de curl va a /dev/null y el script siempre termina con exit 0.
Los hooks PermissionRequest también pueden aprobar o denegar en nombre de Codex. Este no hace ninguna de las dos cosas: no imprime nada, así que Codex muestra su petición de aprobación normal y tú recibes una push que indica que está esperando.
O con la CLI de Pocket Alert
Si tienes instalada la CLI de Pocket Alert 2.0 o posterior, el bloque de curl se reduce a un solo comando. La CLI escapa el texto por sí misma y toma la clave de pocketalert auth, así que ya no hace falta el archivo de clave:
pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true
Mantén -t y -m en lugar de argumentos posicionales: una respuesta que empiece por un guion, como una lista Markdown, se leería como una opción.
Paso 2. Registra los hooks
Crea ~/.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 }
]
}
]
}
}
El archivo en tu directorio personal se aplica en todas partes. Un .codex/hooks.json dentro de un repositorio se aplica a ese proyecto, pero solo después de que marques el proyecto como de confianza.
Los hooks están activados por defecto. Si los desactivaste en algún momento, elimina hooks = false de la tabla [features] en ~/.codex/config.toml.
Codex solo ejecuta los hooks que hayas revisado y marcado como de confianza. La próxima vez que se inicie, avisará de que los hooks nuevos necesitan revisión: abre /hooks, comprueba las dos entradas y márcalas como de confianza. Si los cambias más adelante, Codex los omitirá hasta que vuelvas a confiar en ellos.
Paso 3. Pruébalo
Inicia Codex en cualquier proyecto y dale una tarea corta:
> Summarise README.md in one sentence.
Cuando termine el turno, tu teléfono mostrará Codex finished · your-project con el resumen. Pídele que ejecute un comando que requiera aprobación, y llegará una segunda push, Codex needs approval, con prioridad alta.
Para probar el script sin Codex:
echo '{"hook_event_name":"Stop","cwd":"/tmp/demo","last_assistant_message":"Hook test"}' \
| ~/.codex/hooks/pocketalert.sh
Qué llega a tu teléfono
| Evento | Título | Cuerpo | Nivel |
|---|---|---|---|
| Turno terminado | Codex finished · api | Primeros 300 caracteres de la última respuesta | default |
| Aprobación necesaria | Codex needs approval · api | Wants to run Bash | high |
high se entrega como sensible al tiempo en el iPhone, así que la push de aprobación atraviesa Concentración mientras las notificaciones rutinarias de "terminado" permanecen en silencio. Ambas se guardan en el historial de la app y en el panel web.
La forma antigua: notify
Si tu versión de Codex es anterior a los hooks, o ya usas notify, funciona con algunos cambios. Codex pasa el evento como último argumento en lugar de por stdin, usa claves en kebab-case y solo informa de turnos terminados:
#!/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"]
notify no tiene evento de aprobación, así que usa hooks si quieres saber cuándo Codex está bloqueado.
O deja que Codex lo envíe mediante MCP
Los hooks se activan con eventos fijos. Para que Codex decida qué contarte, añade el servidor MCP de Pocket Alert a ~/.codex/config.toml:
[mcp_servers.pocketalert]
url = "https://mcp.pocketalert.app/mcp"
bearer_token_env_var = "POCKETALERT_API_KEY"
o desde la línea de comandos:
codex mcp add pocketalert --url https://mcp.pocketalert.app/mcp \
--bearer-token-env-var POCKETALERT_API_KEY
Exporta POCKETALERT_API_KEY en la shell desde la que inicias Codex. Así, una petición como "ejecuta la suite de tests y envíame los fallos" termina con Codex llamando a create_message con un resumen que él mismo redactó. La herramienta también acepta level y actions.
Si no llega nada
- Ejecuta el comando de prueba. Si funciona ahí, el problema está en el registro de los hooks; si no, elimina
>/dev/null 2>&1para ver el error de curl.401significa que la clave es incorrecta. - Comprueba que los hooks son de confianza. Abre
/hooksen Codex; los hooks no confiables o modificados se omiten. - Comprueba que el proyecto es de confianza si pusiste
hooks.jsonen el repositorio. - Comprueba que
jqestá en el PATH que ve Codex. Los comandos de los hooks se ejecutan con el entorno de Codex y el directorio de trabajo de la sesión. - Revisa el límite diario. El plan gratuito envía 50 mensajes al día, y Stop se activa después de cada turno.
Preguntas frecuentes
¿Qué pasa con [tui] notifications?
Es la notificación de terminal integrada de Codex. Está activada por defecto y puede cubrir tanto los turnos terminados como las solicitudes de aprobación, pero aparece en el ordenador, a través de tu terminal. Una push llega a tu teléfono y conserva un historial.
¿Esto funciona en la extensión de Codex para el IDE?
La extensión ejecuta el agente de Codex en tu máquina con la misma configuración de ~/.codex, así que configura y marca como de confianza los hooks en la CLI primero. Las tareas de Codex en la nube se ejecutan en los servidores de OpenAI y no ejecutan tus hooks locales.
¿Puedo aprobar desde el teléfono?
No con este script: solo te indica que Codex está esperando. Un hook PermissionRequest puede devolver una decisión de permitir o denegar, así que puedes construir aprobaciones sobre él con un endpoint al que llame tu teléfono. Notificaciones con humano en el bucle muestra el patrón.
¿Es gratis?
Sí. Los hooks vienen integrados en Codex, y el plan gratuito de Pocket Alert cubre 50 mensajes al día en un dispositivo.
Obtén una clave de API, añade el hook y deja de estar pendiente de la terminal.