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

> Recibe una notificación push en tu teléfono cuando Claude Code termina una tarea, espera un permiso o se detiene por un error. Un solo script de hook, tres eventos, sin plugin.

*11.10.2026*

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

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](/account/apikeys). Con el plan gratuito basta.
- La aplicación de Pocket Alert en tu [iPhone o Android](/get-app), 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:

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

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

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

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

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

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:

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

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

<div class="cmp-table-wrap">
<table class="cmp-table">
<thead><tr><th>Evento</th><th>Título</th><th>Cuerpo</th><th>Nivel</th></tr></thead>
<tbody>
<tr><th>Tarea terminada</th><td>Claude finished · api</td><td>Primeros 300 caracteres de la última respuesta de Claude</td><td>default</td></tr>
<tr><th>Solicitud de permiso</th><td>Claude needs you · api</td><td>Claude needs your permission</td><td>high</td></tr>
<tr><th>Esperando entrada</th><td>Claude needs you · api</td><td>Claude is waiting for your input</td><td>high</td></tr>
<tr><th>Error de la API</th><td>Claude stopped · api</td><td>API error: rate_limit</td><td>high</td></tr>
</tbody>
</table>
</div>

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

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

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

## 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](/signup), añade el script y deja que Claude te avise cuando sea tu turno.
