El Notification hook de Claude Code: cuándo se dispara y cómo usarlo

01Los tipos de notificación

El matcher de un hook Notification es el tipo de notificación. Déjalo vacío para que se ejecute con todos, o indica los que quieras separados por |. Los tipos que más probablemente usarás:

Hay más, como agent_needs_input y agent_completed para sesiones en segundo plano en la vista de agentes, y un conjunto de tipos quota_auto_resume_* para las esperas por límite de uso. La referencia de hooks tiene la lista completa y actualizada.

02Las reglas de tiempo

Aquí es donde mucha gente se confunde. El hook Notification comparte la temporización con las notificaciones de escritorio de Claude Code, así que en una sesión de terminal solo se dispara cuando dejas de prestar atención:

• permission_prompt inicia un temporizador de unos seis segundos cuando aparece el prompt. Cada pulsación de tecla lo reinicia. Si respondes rápido, nunca se dispara.
• idle_prompt se dispara unos 60 segundos después de que Claude termine, solo si no has escrito nada desde entonces y no queda ningún agente en segundo plano en ejecución. No se dispara mientras Claude Code espera a que se restablezca un límite de uso.
• Una solicitud que llega mientras hay otro diálogo abierto se temporiza desde que llega, así que su notificación puede llegarte mientras aún espera detrás del diálogo abierto.

Los hosts que responden a los permisos mediante el Agent SDK, como Claude Desktop y la extensión de VS Code, temporizan permission_prompt de otra forma: unos seis segundos después de la solicitud, sin que escribir lo retrase, y se omite si tú o un hook PermissionRequest respondéis antes.

Si quieres un aviso sin retraso, usa otro evento:

03Qué recibe el hook

Además de los campos comunes (session_id, transcript_path, cwd, hook_event_name), un hook Notification recibe el message de la notificación, un title opcional y el notification_type:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

El message es el texto del propio Claude Code, así que puedes mostrarlo tal cual sin problema. cwd resulta útil cuando tienes varias sesiones abiertas y quieres saber qué proyecto te está preguntando.

04Qué puede y qué no puede hacer el hook

Un hook Notification no puede bloquear, retrasar ni modificar la notificación. Su código de salida y su stderr se ignoran, y Claude Code descarta systemMessage y continue de su salida JSON. Sirve únicamente para efectos secundarios.

Hay un campo de salida que sí puede usar: terminalSequence. Los hooks se ejecutan sin terminal, así que no pueden escribir secuencias de escape por sí mismos, pero pueden pasarle una a Claude Code para que la emita. Así un hook puede lanzar una notificación nativa del terminal en iTerm2, Ghostty, Kitty, WezTerm, Windows Terminal y otros, incluso dentro de tmux. Solo funciona en una sesión interactiva con la interfaz de Claude Code en pantalla.

El ajuste preferredNotifChannel tampoco detiene el hook. Aunque desactives las notificaciones integradas, el evento Notification se sigue disparando. Ese ajuste solo cambia cómo te avisa el propio Claude Code; consulta la guía de la campana del terminal.

05Ejemplos

Un handler distinto para cada tipo

Ejecuta un script diferente para los prompts de permisos y para los recordatorios de inactividad:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/permission-alert.sh" }]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/idle-alert.sh" }]
      }
    ]
  }
}

Haz cada script ejecutable con chmod +x. Los comandos de notificación de escritorio para Mac, Windows y Linux están en cómo recibir una notificación cuando Claude Code termina, así que no los repetimos aquí.

Mostrar el mensaje real y el proyecto

Este script (macOS y Linux) pone en la notificación el mensaje de Claude Code y la carpeta del proyecto, en lugar de un texto fijo:

#!/bin/bash
# ~/.claude/hooks/notify.sh
input=$(cat)
msg=$(jq -r '.message // "Claude Code needs your attention"' <<<"$input")
project=$(basename "$(jq -r '.cwd // "."' <<<"$input")")

if command -v osascript >/dev/null 2>&1; then
  osascript -e 'on run argv' \
            -e 'display notification (item 1 of argv) with title (item 2 of argv)' \
            -e 'end run' "$msg" "Claude Code: $project"
elif command -v notify-send >/dev/null 2>&1; then
  notify-send "Claude Code: $project" "$msg"
fi
exit 0

Pasar el texto como argumentos (on run argv) evita que el AppleScript se rompa cuando el mensaje contiene comillas. Necesita jq instalado.

Una notificación nativa del terminal

El propio ejemplo de Anthropic usa terminalSequence con OSC 777, que entienden Ghostty, Warp y urxvt:

#!/bin/bash
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'

Para iTerm2, Windows Terminal o WezTerm usa OSC 9, y para Kitty OSC 99. Cualquier secuencia fuera de las permitidas se ignora.

06Dónde encaja Claude Code Notifier

Un hook Notification que llama a un servicio de push te hace llegar el aviso al móvil, y para mucha gente con eso basta. La guía de ntfy explica cómo hacerlo.

Lo que falta es poder responder. Cuando se dispara permission_prompt, Claude está esperando un diálogo que un hook Notification no puede contestar. Claude Code Notifier lo resuelve con los hooks que sí pueden: PermissionRequest para devolver tu decisión y PreToolUse sobre AskUserQuestion para devolver tu respuesta. Su herramienta de línea de comandos gratuita, ccn, funciona en Mac, Windows y Linux y muestra notificaciones de escritorio por sí sola. Con la app de iPhone o Android vinculada, puedes permitir una vez, permitir para toda la sesión o denegar desde el móvil. Si has escrito en los últimos 30 segundos, no se espera al móvil y el terminal pregunta como siempre. Es una herramienta independiente y no está hecha por Anthropic. Tienes las instrucciones de instalación en la página de ccn.

07Preguntas frecuentes