Volver al blog

Notificaciones push para Claude Code: entérate cuando termina una tarea

Notificaciones push para Claude Code: entérate cuando termina una tarea

Claude Code puede trabajar veinte minutos por su cuenta sin problemas. El problema está en lo que pasa después: o te quedas mirando la terminal, o te alejas y, al volver, descubres que lleva esperando un permiso desde el minuto tres.

Los hooks resuelven los dos casos. Claude Code ejecuta un comando de shell en puntos fijos de su ciclo de vida, y tres de esos puntos son justo lo que quieres en tu teléfono:

  • Stop: Claude terminó de responder. La tarea está lista o tiene una pregunta.
  • Notification: Claude te necesita. Muestra una solicitud de permiso o lleva inactivo esperando tu respuesta.
  • StopFailure: el turno terminó por un error de la API, como un límite de uso o un problema de facturación.

Esta guía conecta los tres eventos a Pocket Alert con un solo script. La configuración tarda unos cinco minutos.

Lo que necesitas

  • Claude Code, cualquier versión reciente.
  • jq y curl. Vienen instalados en la mayoría de distribuciones de Linux; en macOS, usa brew install jq.
  • Una cuenta de Pocket Alert y una clave de API de Claves de API. Con el plan gratuito basta.
  • La aplicación de Pocket Alert en tu iPhone o Android, con la sesión iniciada.

Paso 1. El script del hook

Claude Code pasa a cada hook un objeto JSON por stdin. Los campos que necesitas son hook_event_name, cwd, last_assistant_message en Stop, message en Notification y error en StopFailure. El script convierte esos datos en una notificación 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

Guárdalo como ~/.claude/hooks/pocketalert.sh y hazlo ejecutable:

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

Dos líneas del script son más importantes de lo que parecen:

  • jq -n construye el JSON. El último mensaje de Claude está lleno de comillas, backticks y saltos de línea. Pegarlo a mano dentro de una cadena JSON se rompe con la primera comilla; jq escapa todo correctamente.
  • exit 0 al final, y || true después de curl. En un hook de Stop, el código de salida 2 significa "no te detengas, sigue". Un hook de notificación nunca debe bloquear a Claude, ni siquiera cuando tu red está caída.

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_API_KEY (el bloque env de abajo la define) o de pocketalert auth:

pocketalert send -t "$title" -m "${message:0:300}" -l "$level" -q >/dev/null 2>&1 || true

Usa -t y -m en lugar de argumentos posicionales: una respuesta que empiece con un guion, como una lista de Markdown, se interpretaría como una opción.

Paso 2. Registra los hooks

Añade los hooks a ~/.claude/settings.json para que se apliquen a todos los proyectos. Si el archivo ya tiene una clave hooks, combina estas entradas con ella:

{
  "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" }]
      }
    ]
  }
}

El bloque env entrega la clave de API al hook sin que tengas que ponerla en tu perfil de shell. Si ya exportas POCKETALERT_API_KEY en otro lugar, omite ese bloque.

El matcher de Notification filtra por tipo de notificación. permission_prompt se activa cuando una solicitud de permiso lleva unos seis segundos sin respuesta, e idle_prompt unos sesenta segundos después de que Claude termine, si no has escrito nada desde entonces. En una sesión de terminal, ambos solo se activan cuando pareces haberte alejado, así que no hacen vibrar tu teléfono mientras estás mirando. Stop no tiene matcher: se activa cada vez que Claude termina una respuesta.

Para limitar los hooks a un solo repositorio, pon el mismo bloque hooks en .claude/settings.json dentro de ese repositorio, o en .claude/settings.local.json si no quieres que entre en git.

Paso 3. Pruébalo

Claude Code normalmente detecta por sí mismo los cambios en el archivo de configuración (inicia una sesión nueva si /hooks todavía no los muestra). Dale una tarea sencilla:

> List the files in this directory and stop.

Cuando Claude termine, tu teléfono mostrará Claude finished · your-project con el inicio de su respuesta. Si no llega nada, ejecuta /hooks dentro de Claude Code para ver los hooks registrados.

Para probar el script por separado, pásale un 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

Lo que llega a tu teléfono

EventoTítuloCuerpoNivel
Tarea terminadaClaude finished · apiPrimeros 300 caracteres de la última respuesta de Claudedefault
Solicitud de permisoClaude needs you · apiClaude needs your permissionhigh
Esperando entradaClaude needs you · apiClaude is waiting for your inputhigh
Error de la APIClaude stopped · apiAPI error: rate_limithigh

high llega como notificación sensible al tiempo en iPhone, así que una solicitud de permiso atraviesa la Concentración, mientras que los avisos rutinarios de "terminado" se mantienen en silencio. Cada push también queda en el historial de la aplicación y en el panel web, para que puedas revisar lo que Claude hizo durante la noche.

Adáptalo a tu forma de trabajar

Solo cuando no estés. Stop se activa después de cada respuesta, incluidas las rápidas que estás viendo. Añade un interruptor al principio del script:

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

Luego ejecuta touch ~/.claude/away cuando te vayas de la mesa y rm ~/.claude/away cuando vuelvas. Las solicitudes de permiso merecen siempre tu atención, así que puedes poner la comprobación solo dentro de la rama Stop).

Agrupa por proyecto. Crea una aplicación por proyecto en Pocket Alert y añade application_id al JSON. La aplicación filtrará por proyecto y podrás asignar a cada uno su propio nivel por defecto.

No bloquees a Claude en absoluto. Añade "async": true junto a "type": "command" y el hook se ejecutará en segundo plano. Omítelo en ejecuciones sin interfaz (claude -p): los hooks en segundo plano se cancelan cuando termina la sesión y es posible que la notificación nunca se envíe.

Responde desde el teléfono. Con un plan de pago, un botón de acción de tipo copy con el ID de la sesión te permite copiar claude --resume <id> desde el teléfono y pegarlo cuando vuelvas.

O deja que Claude lo envíe con MCP

Los hooks son deterministas: se activan tanto si Claude recuerda avisarte como si no. La otra vía es darle a Claude una herramienta de notificaciones y dejar que decida cuándo usarla. Añade el servidor MCP de Pocket Alert:

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

Ahora puedes decir "ejecuta la migración y envíame el número de filas cuando termine", y Claude llamará a create_message con un mensaje que escribe para la ocasión. La herramienta también acepta level y actions, y list_messages permite a Claude consultar lo que envió antes.

Usa ambos: los hooks para el aviso garantizado de "terminado" y "te necesito", y MCP para mensajes con contenido concreto. Para aprobaciones antes de pasos arriesgados, consulta Notificaciones con intervención humana.

Si no llega nada

  • Revisa la clave. Ejecuta el comando de prueba de arriba. Un 401 de curl significa que la clave de API es incorrecta; quita >/dev/null para ver la respuesta.
  • Comprueba que los hooks se cargaron. Ejecuta /hooks. Los cambios en el archivo de configuración suelen detectarse en segundos; si los hooks no aparecen, reinicia Claude Code.
  • Comprueba que jq está en el PATH que usa Claude Code. Los hooks se ejecutan con el entorno de Claude, y un editor abierto desde la interfaz gráfica puede no ver /opt/homebrew/bin de Homebrew.
  • Revisa el límite diario. El plan gratuito envía 50 mensajes al día. Una sesión larga con muchas respuestas cortas puede agotarlo; el interruptor de "ausente" de arriba ayuda.

Preguntas frecuentes

¿Funciona en las extensiones de VS Code y JetBrains?

Sí. Las extensiones ejecutan Claude Code por debajo y leen el mismo ~/.claude/settings.json, así que los hooks también se activan allí.

¿Claude puede ver la clave de API?

No en la conversación: los hooks se ejecutan fuera de ella, y su salida para Stop y Notification no se muestra al modelo. Pero el bloque env se aplica a toda la sesión, así que un comando Bash que Claude ejecute podría leer la variable. Si eso te preocupa, guarda la clave en un archivo que solo tú puedas leer, como ~/.config/pocketalert/key con modo 600, y usa -H "Token: $(cat ~/.config/pocketalert/key)" en el script.

¿En qué se diferencia de la campana de la terminal?

La campana y las notificaciones de escritorio requieren que estés frente al ordenador. Un push llega a tu teléfono estés donde estés, guarda un historial y puede configurarse para atravesar la Concentración en las solicitudes que bloquean a Claude.

¿Puedo recibir la respuesta completa, no solo 300 caracteres?

Un push admite hasta unos 3.000 caracteres de texto. Puedes aumentar el límite 0:300, pero un push sirve para decidir si vuelves a la mesa, no para leer la respuesta completa.

¿Es gratis?

Sí. Los hooks forman parte de Claude Code, y el plan gratuito de Pocket Alert incluye 50 mensajes al día en un dispositivo. Los planes de pago añaden más mensajes, dispositivos y botones de acción.

Obtén una clave de API, añade el script y deja que Claude te avise cuando sea tu turno.

Comparte este artículo