Notificaciones de Claude Code en macOS

01Qué hace Claude Code por sí solo

Claude Code lanza un evento de notificación cuando termina una tarea o espera un permiso y parece que no estás en el terminal. Lo que ves depende del terminal, según la guía de terminal de Anthropic:

En iTerm2, abre Settings > Profiles > Terminal, marca Notification Center Alerts, luego haz clic en Filter Alerts y activa Send escape sequence-generated alerts. Comprueba también que iTerm2 tiene permiso para enviar notificaciones en Ajustes del Sistema > Notificaciones.

En Apple Terminal al menos puedes tener sonido. Pon "preferredNotifChannel": "terminal_bell" en ~/.claude/settings.json y activa Campana audible en Ajustes > Perfiles > Avanzado. La guía de la campana del terminal explica esta opción en detalle.

La alerta integrada tiene sus límites. Solo salta cuando Claude Code cree que no estás, solo dice que ha pasado algo y nunca sale del ordenador.

02Un hook de notificación con osascript

Un hook funciona en cualquier terminal, incluidos los de los IDE. Este es el ejemplo para macOS de la guía de hooks de Anthropic. Añádelo a ~/.claude/settings.json, conservando las demás claves que ya tengas:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Escribe /hooks en Claude Code para confirmar que aparece en Notification.

El permiso de Editor de Scripts

osascript publica las notificaciones como Editor de Scripts. Si Editor de Scripts no tiene permiso de notificaciones, el comando falla en silencio y macOS no pregunta. Ejecuta esto una vez en Terminal:

osascript -e 'display notification "test"'

La primera vez no aparece nada. Abre Ajustes del Sistema > Notificaciones, busca Editor de Scripts y activa Permitir notificaciones. Vuelve a ejecutar el comando y debería salir la notificación de prueba.

Cuándo se dispara

El matcher vacío salta con cualquier tipo de notificación. Los dos que más te interesan son permission_prompt (Claude lleva unos seis segundos esperando una aprobación y no has escrito nada) e idle_prompt (Claude terminó hace unos 60 segundos y no has escrito nada desde entonces). La guía del Notification hook enumera todos los tipos y sus tiempos.

03Entérate en cuanto Claude termine

idle_prompt espera un minuto. Para enterarte al instante, añade un hook Stop, que se ejecuta cuando Claude termina su turno. Stop no lleva matcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude has finished\" with title \"Claude Code\" sound name \"Glass\"'"
          }
        ]
      }
    ]
  }
}

sound name admite cualquier sonido de /System/Library/Sounds, como Glass, Ping o Hero. Si solo quieres sonido, puedes usar afplay /System/Library/Sounds/Glass.aiff como comando. Más sobre este evento en la guía del Stop hook.

04Muestra el mensaje real

Los hooks reciben JSON por la entrada estándar. La entrada de Notification tiene un campo message, como "Claude needs your permission". Un pequeño script puede poner ese texto en la notificación. Guárdalo como ~/.claude/hooks/notify-mac.sh:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
osascript -e 'on run argv' \
  -e 'display notification (item 1 of argv) with title "Claude Code"' \
  -e 'end run' "$msg"

Al pasar el texto como argumento y no dentro de la cadena de AppleScript, las comillas del mensaje no pueden romper el comando. Hazlo ejecutable con chmod +x ~/.claude/hooks/notify-mac.sh y pon ~/.claude/hooks/notify-mac.sh como comando del hook. El script necesita jq (brew install jq si jq --version falla).

05terminal-notifier: haz clic para volver a tu terminal

Al hacer clic en una notificación de osascript se abre Editor de Scripts, que no es adonde quieres ir. terminal-notifier te deja elegir qué app pasa al frente:

brew install terminal-notifier
terminal-notifier -title "Claude Code" -message "Claude has finished" -sound default -activate com.googlecode.iterm2

Usa com.apple.Terminal para Apple Terminal, o el bundle ID de tu editor. El mismo comando va en el campo command del hook. La primera vez, permite las notificaciones de terminal-notifier en Ajustes del Sistema.

06Concentración y No molestar

Todas son notificaciones normales de macOS, así que un modo de Concentración puede ocultarlas. Si desaparecen a ciertas horas, revisa Ajustes del Sistema > Concentración y permite la app que las publica (Editor de Scripts, terminal-notifier o tu terminal). Si prefieres notificaciones que respeten tus propios horarios, consulta horas de silencio y No molestar.

07Dónde encaja Claude Code Notifier

Los hooks anteriores son buena solución si estás delante del Mac y solo quieres un aviso. Se quedan cortos cuando te alejas, porque una notificación del Mac no te llega a la cocina ni puede responder a Claude.

Claude Code Notifier es una herramienta independiente (creada por TouchTap, no por Anthropic) basada en los mismos hooks. Su herramienta de línea de comandos gratuita, ccn, funciona en Mac, Windows y Linux. Instálala en tu Mac con:

curl -fsSL https://claudecodenotifier.com/install.sh | sh

o con Homebrew: brew trust --formula touch-tap/tap/ccn && brew install touch-tap/tap/ccn. Añade sus entradas de hook a ~/.claude/settings.json, no toca el resto del archivo y guarda una copia de seguridad. A partir de ahí muestra una notificación de macOS cuando Claude termina, necesita un permiso o hace una pregunta, sin red ni móvil.

Si vinculas un iPhone o un móvil Android, los mismos eventos te llegan como notificaciones push, y desde el móvil puedes permitir o denegar un permiso, elegir una respuesta a la pregunta de Claude o enviar la siguiente instrucción. Si has escrito en los últimos 30 segundos, el terminal pregunta como siempre y no queda nada pendiente en el móvil. Consulta vincular un móvil y la página de ccn. Las apps móviles requieren una suscripción o una compra de por vida; consulta los precios.

Si añades ccn, quita tus propios hooks de osascript o verás dos notificaciones por cada evento. También hay una app antigua para la barra de menús del Mac; no la uses junto con ccn en el mismo Mac.

08Preguntas frecuentes