¿No funcionan las notificaciones de Claude Code? Una checklist

011. Comprueba que Claude Code ha cargado el hook

Escribe /hooks en el prompt de Claude Code. Es un navegador de solo lectura con todos los hooks que Claude Code ha cargado, y cada uno indica de dónde viene: ajustes de usuario, de proyecto, locales, un plugin o la sesión actual. Selecciona un hook para ver el comando exacto y el archivo donde está definido.

Si tu hook no aparece en la lista:

• El JSON no es válido. Los archivos de ajustes son JSON estricto. Una coma final o un comentario // rompen el archivo, y Claude Code muestra un Settings Error en el siguiente arranque. Ejecuta claude doctor para ver las entradas que Claude Code ha rechazado.
• El archivo está en el sitio equivocado. Los hooks personales van en ~/.claude/settings.json (en Windows, %USERPROFILE%\.claude\settings.json). Los hooks de proyecto van en .claude/settings.json dentro del proyecto. Ejecuta /status y mira la línea Setting sources para ver qué archivos se cargaron.
• El nombre del evento es incorrecto. Los nombres de eventos distinguen mayúsculas y minúsculas: Notification, Stop, PermissionRequest. Un nombre desconocido aparece como Settings Warning y se ignora.
• Los hooks están desactivados. "disableAllHooks": true en cualquier archivo de ajustes desactiva todos los hooks. Si /hooks muestra Only hooks from managed settings run here, tu organización ha configurado allowManagedHooksOnly y tus propios hooks no se ejecutarán.
• No se detectó el cambio. Claude Code normalmente recarga los ajustes solo. Si el hook no aparece tras unos segundos, reinicia la sesión.

022. Acepta la confianza del espacio de trabajo

En una sesión interactiva, Claude Code retiene los hooks de todos los archivos de ajustes, incluido tu ~/.claude/settings.json, hasta que aceptas el diálogo de confianza del espacio de trabajo para esa carpeta. Si cerraste ese diálogo, o estás en una carpeta donde nunca has abierto Claude Code, tus hooks no se ejecutarán ahí. Inicia claude en esa carpeta y acepta el diálogo.

033. Asegúrate de que el evento se dispara cuando crees

Muchas notificaciones "rotas" son en realidad un tema de timing. Según la referencia de hooks de Anthropic:

Así que si pruebas un hook de Notification mientras escribes en la terminal, puede que nunca se dispare. Cambia a otra ventana y espera. Para recibir un aviso en cuanto termina un turno, usa Stop; la guía del Stop hook lo explica.

Revisa también tu modo de permisos. Las versiones recientes de Claude Code inician las sesiones interactivas en modo auto, donde un clasificador aprueba la mayoría de acciones sin preguntar. Sin aviso no hay notificación permission_prompt ni hook PermissionRequest. Para probar los avisos de permisos, pulsa Shift+Tab hasta que la barra de estado muestre el modo manual y pídele a Claude algo que necesite aprobación. En Modos de permisos explicados tienes los detalles.

Los matchers también distinguen mayúsculas y minúsculas. Un matcher de PermissionRequest con bash no coincidirá con la herramienta Bash.

044. Ejecuta tú mismo el comando del hook

Copia el comando desde /hooks y ejecútalo en una terminal con una entrada de ejemplo:

echo '{"hook_event_name":"Stop","cwd":"/tmp","last_assistant_message":"done"}' | ./my-hook.sh
echo $?

Fallos habituales:

• command not found: usa una ruta absoluta al script, o ${CLAUDE_PROJECT_DIR} para scripts del proyecto.
• El script no hace absolutamente nada: hazlo ejecutable con chmod +x ./my-hook.sh.
• jq: command not found: instala jq, o parsea el JSON con Python o Node.js.

055. Lee el log de depuración

Inicia Claude Code con claude --debug. No se imprime nada extra en la terminal; el log va a ~/.claude/debug/<session-id>.txt. Para elegir la ruta, usa claude --debug-file /tmp/claude.log y ejecuta tail -f /tmp/claude.log en otra terminal. Si la sesión ya está en marcha, /debug activa el log y te dice dónde está.

Busca las líneas que empiezan por Hooks:. Cada una indica el evento, el comando, cómo terminó (finished with status 0, timed out, failed to start) y cuánto tardó. Para más detalle sobre los matchers, define CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose.

Hay dos problemas que solo se ven aquí:

• Tu perfil de shell imprime algo. Si ~/.bashrc o ~/.zshrc ejecuta un echo y la shell lo carga, ese texto aparece delante de la salida JSON de tu hook, y Claude Code trata la salida como texto plano. Busca en el log Hook output does not start with {. Envuelve la salida del perfil en if [[ $- == *i* ]]; then ... fi para que solo se ejecute en shells interactivas.
• No hay terminal donde escribir. En Mac y Linux, los hooks de comando se ejecutan sin terminal de control. Un hook que intente hacer sonar la campana o escribir códigos de escape en /dev/tty falla sin avisar. Usa un comando de notificación de escritorio, o el ajuste preferredNotifChannel del propio Claude Code, que se explica en la guía de la campana de la terminal.

066. Revisa el sistema operativo

Si el log de depuración dice que el hook terminó con estado 0 y aun así no viste nada, lo ocultó el sistema operativo. Comprueba que la app que lanza el aviso tiene permiso para mostrar notificaciones y que Concentración (Mac), No molestar (Windows) o el modo no molestar de tu escritorio Linux están desactivados. En Linux, además, tiene que haber un daemon de notificaciones en ejecución.

Tienes los comandos de cada plataforma en las guías de macOS, Windows y Linux.

07Si usas Claude Code Notifier

Claude Code Notifier es una herramienta independiente (no la hace Anthropic) que instala un pequeño programa, ccn, como hooks de Claude Code. Todo lo anterior sigue siendo válido, porque ccn es un hook como cualquier otro. Empieza por sus propias comprobaciones:

1. ccn doctor revisa los hooks, las credenciales, la conexión con el servidor y la detección de presencia. Arregla primero lo que te indique.
2. ccn test envía una notificación de prueba. Si llega, el problema está en el evento o en algún ajuste, no en el pipeline.
3. ccn devices muestra los teléfonos vinculados con este ordenador. Si no aparece ninguno, vuelve a vincular con ccn pair; la guía de vinculación te explica cómo.
4. ccn config show muestra los ajustes efectivos. Comprueba que notify_on_done, notify_on_permission y notify_on_question están activados y que quiet_hours no incluye la hora actual. Los ajustes que cambies en el teléfono llegan al ordenador con ccn sync.

Algunos comportamientos parecen fallos, pero son intencionados:

• Estás delante del teclado. Si has escrito en los últimos 30 segundos, no se espera al teléfono y la terminal pregunta como siempre. Con quiet_when_present activado (por defecto), el teléfono no recibe nada mientras estás en la terminal donde corre Claude, y recibe una tarjeta informativa si estás activo en otra app.
• Avisos duplicados o que faltan en un Mac. No uses a la vez la antigua app de la barra de menús de Mac y ccn en el mismo Mac.
• Mucho tiempo sin uso. Si un teléfono u ordenador no se usa durante 60 días, el servidor borra su vinculación y tendrás que vincularlo de nuevo.

En el propio teléfono, comprueba que la app tiene permiso para mostrar notificaciones y que Concentración (iPhone) o No molestar (Android) no la están silenciando. En Android, la optimización de batería puede retrasar las notificaciones de algunas apps; si los avisos llegan tarde, permite que la app funcione sin restricciones en sus ajustes de batería. Si editaste settings.json a mano, ccn doctor te dice si sus hooks siguen en su sitio. ccn upgrade actualiza a la última versión.

08Preguntas frecuentes