Notificaciones de Claude Code en Linux

01Qué hace Claude Code por sí solo

Cuando Claude termina una tarea o espera un permiso y parece que no estás, Claude Code lanza un evento de notificación. Según la guía de terminal de Anthropic, Ghostty y Kitty lo convierten en una notificación de escritorio; otros terminales, como GNOME Terminal, Konsole o el terminal de VS Code, no muestran nada.

En su lugar, puedes pedir un aviso sonoro (bell) en cualquier terminal:

{
  "preferredNotifChannel": "terminal_bell"
}

Lo que hace el bell depende del terminal y del escritorio: puede pitar, parpadear o marcar la ventana como urgente. Lo explicamos en la guía del terminal bell. Para una notificación de verdad, usa un hook.

02Instala notify-send

Comprueba si lo tienes:

notify-send 'Claude Code' 'test'

Si no encuentra el comando, instálalo:

sudo apt install libnotify-bin   # Debian, Ubuntu, Mint
sudo dnf install libnotify       # Fedora, RHEL
sudo pacman -S libnotify         # Arch

Si el comando se ejecuta pero no aparece nada, no tienes daemon de notificaciones. GNOME, KDE Plasma, Cinnamon y Xfce traen uno. En un gestor de ventanas en mosaico como Sway, i3 o Hyprland, instala y arranca uno tú mismo, por ejemplo mako o dunst. Funciona tanto en Wayland como en X11, porque notify-send habla con el daemon por D-Bus, no con el servidor gráfico.

03Un Notification hook

Este es el ejemplo para Linux de la guía de hooks de Anthropic. Añádelo a ~/.claude/settings.json, junto a las claves que ya tengas:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

Escribe /hooks en Claude Code para verlo en Notification. El matcher vacío se dispara con cualquier tipo de notificación. Los principales son permission_prompt, cuando una aprobación lleva unos seis segundos esperando sin que escribas, e idle_prompt, unos 60 segundos después de que Claude termine. La lista completa está en la guía del Notification hook.

04Entérate en cuanto Claude termine

idle_prompt llega con un minuto de retraso. Un hook Stop se ejecuta en cuanto Claude acaba su turno. No lleva matcher:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "notify-send -a 'Claude Code' 'Claude Code' 'Claude has finished'"
          }
        ]
      }
    ]
  }
}

-a define el nombre de la app que muestra el daemon. Otras opciones útiles: -u critical mantiene la notificación en pantalla hasta que la cierres en la mayoría de daemons, y -i dialog-information añade un icono. Más sobre este evento en la guía del Stop hook.

05Muestra el mensaje real, con sonido

Los hooks reciben JSON por la entrada estándar, y la entrada de Notification incluye un campo message. Un script puede mostrar ese texto y reproducir un sonido. Guarda esto como ~/.claude/hooks/notify-linux.sh:

#!/bin/bash
msg=$(jq -r '.message // "Claude Code needs your attention"')
notify-send -a 'Claude Code' 'Claude Code' "$msg"
paplay /usr/share/sounds/freedesktop/stereo/complete.oga 2>/dev/null || true

Hazlo ejecutable con chmod +x ~/.claude/hooks/notify-linux.sh y usa ~/.claude/hooks/notify-linux.sh como comando del hook. jq está en los paquetes de cualquier distribución. paplay funciona con PulseAudio y con la capa PulseAudio de PipeWire, y el archivo de sonido viene del tema de sonidos de freedesktop (sound-theme-freedesktop en Debian y Ubuntu). Puedes usar cualquier .oga o .wav que quieras.

06¿Sin notify-send? Usa una secuencia de escape

Si tu terminal entiende secuencias de escape de notificación, un hook puede pedirle a Claude Code que envíe una. Los hooks no tienen terminal propio, así que devuelves la secuencia en un campo terminalSequence y Claude Code la escribe. La referencia de Anthropic indica OSC 777 para Ghostty, urxvt y Warp, y OSC 99 para Kitty. Por ejemplo:

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

Esto no necesita ningún daemon en la máquina donde corre Claude Code, y por eso también es el truco para servidores remotos por SSH.

07Cuando notify-send funciona en una shell pero no desde Claude Code

notify-send necesita la dirección del bus de sesión D-Bus de tu sesión de escritorio. Los hooks heredan el entorno de Claude Code, así que si arrancas Claude Code desde una terminal del escritorio, no hay problema. Si arrancas Claude Code por SSH, desde un servicio de systemd, en un contenedor o dentro de un servidor de tmux que se inició por primera vez desde SSH, puede que no la tenga, y la notificación se pierde. Ejecuta echo $DBUS_SESSION_BUS_ADDRESS en la misma shell desde la que lanzas claude; si sale vacío, las notificaciones de escritorio de esa sesión no se mostrarán. La guía de tmux y la guía de SSH explican esas configuraciones.

08Dónde encaja Claude Code Notifier

Los hooks de arriba son buena opción cuando trabajas delante de la máquina. Pero no te avisan si te levantas de la mesa, y una notificación de escritorio no puede responder a Claude.

Claude Code Notifier es una herramienta independiente (hecha por TouchTap, no por Anthropic) basada en los hooks de Claude Code. Su herramienta de línea de comandos gratuita, ccn, funciona en Mac, Windows y Linux. En Linux:

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

o npx @touchtap/ccn si tienes Node.js. Añade sus entradas de hook a ~/.claude/settings.json, deja todo lo demás como estaba y guarda una copia de seguridad. A partir de ahí, muestra una notificación de escritorio en Linux cuando Claude termina, necesita un permiso o hace una pregunta. Esa parte no necesita red ni móvil. Se ejecuta unos milisegundos por evento; no queda nada corriendo en segundo plano.

Empareja un iPhone o un móvil Android y esos mismos eventos te llegarán como notificaciones push, incluso en una máquina sin escritorio. Desde el móvil puedes permitir o denegar un permiso, elegir una respuesta a la pregunta de Claude y enviar la siguiente instrucción cuando Claude termine. Consulta cómo emparejar un móvil, la página de ccn y los precios de las apps móviles. En Linux, ccn guarda su token en un archivo que solo tú puedes leer.

Si instalas ccn, elimina tus propios hooks de notify-send para evitar duplicados.

09Preguntas frecuentes