ianotifier 🔔

Un sistema universal de notificaciones de escritorio para Ubuntu GNOME, diseñado para que las inteligencias artificiales (como Claude y Antigravity) te avisen visualmente, con bips acústicos y mediante síntesis de voz (Text-to-Speech) cuando finalicen sus tareas.

---

🚀 Características

• Detección Automática de Idioma: Autodetecta si el mensaje está en inglés o español para hablar con la pronunciación y acento correctos de forma nativa.
• Cero dependencias externas: Implementado en Python 3 estándar. No requiere instalaciones con pip ni entornos virtuales.
• Mapeo de IA (Voces y Tonos): Distingue qué IA te habla por su perfil acústico (ej. Claude con voz masculina, Antigravity con voz femenina).
• Instalación en un Paso: Empaquetado como un .deb Debian nativo.
• Protocolo Unificado: Soporta llamadas directas desde consola y el estándar MCP (Model Context Protocol).

---

🛠️ Compilación e Instalación

1. 📦 Construcción del paquete .deb

Para generar el paquete .deb ejecutable a partir del código fuente (ubicado en src/), ejecuta el script de compilación incluido en la raíz del proyecto:

./build_deb.sh

Este script se encargará de establecer los permisos correctos a los archivos ejecutables y scripts de pre/post-instalación, empaquetándolos en ianotifier_1.0.0-1_all.deb utilizando dpkg-deb.

2. 🚀 Instalación

Una vez compilado el paquete, puedes instalarlo ejecutando el siguiente comando:

sudo apt install ./ianotifier_1.0.0-1_all.deb

Nota: apt install instalará automáticamente todas las dependencias del sistema requeridas (libnotify-bin, speech-dispatcher, alsa-utils) si no las tienes.

Tras la instalación, los comandos ianotifier e ianotifier-mcp estarán registrados globalmente en tu sistema. Los archivos de sonido por defecto se generarán automáticamente en /usr/share/ianotifier/sounds/.

---

⚙️ Configuración en Clientes de IA

1. Claude Desktop

Abre tu archivo de configuración de Claude Desktop (suele estar en ~/.config/Claude/claude_desktop_config.json) y agrega el servidor en la sección mcpServers:

{
  "mcpServers": {
    "ianotifier": {
      "command": "ianotifier-mcp"
    }
  }
}

2. VSCode (Cline / Roo-Cline / Roo-Code / etc.)

En la pestaña de configuración del plugin en VSCode, en la sección de MCP:

1. Agrega un nuevo servidor de tipo stdio.
2. Name: ianotifier
3. Command: ianotifier-mcp

3. Integración de la IA (Skills y Reglas de Workspace)

Para que las inteligencias artificiales (como Claude, Antigravity, etc.) conozcan cómo y cuándo enviar notificaciones a través de la línea de comandos o mediante el servidor MCP de forma óptima, se utiliza una Skill dedicada.

Por favor, consulta y remite a la IA al archivo de skill ianotifier_skill.md, el cual contiene la fuente de verdad única para:

• Guía detallada de comandos CLI para IAs que corren en consola (agy, claude-cli).
• Parámetros esperados y ejemplos del protocolo MCP.
• Reglas de espacio de trabajo (GEMINI.md, .clinerules, .cursorrules, etc.) para evitar el consumo innecesario de tokens.

---

🐳 Integración con Docker y SSH (Desarrollo Remoto)

Cuando ejecutas tus entornos de desarrollo de IA dentro de contenedores Docker o en servidores remotos vía SSH, ianotifier permite enviar las notificaciones a través de la red para que se ejecuten y reproduzcan físicamente en tu ordenador local (donde tienes tus altavoces y pantalla).

A continuación se detalla la configuración para cada caso estructurado por: Escenario ➔ Comando ➔ Para qué sirve.

---

Caso A: Contenedores Docker Locales

Este caso aplica si estás ejecutando contenedores Docker en tu misma máquina local (como Dev Containers de VS Code).

Paso 1

• Escenario: En tu máquina física principal (Host).
• Comando:

  ianotifier listen 8088 0.0.0.0

• Para qué sirve: Arranca el servidor de escucha local en el puerto 8088 enlazándolo a todas las interfaces de red (0.0.0.0), permitiendo que el puente de red interno de Docker se comunique con el host.

Paso 2

• Escenario: Al arrancar el contenedor Docker (desde tu máquina host).
• Comando:

  docker run --add-host=host.docker.internal:host-gateway -it tu_imagen_ia

• Para qué sirve: Arranca el contenedor mapeando la IP del gateway del host al nombre de dominio host.docker.internal. Esto permite al código dentro de Docker conocer y llamar a la IP del host.

Paso 3 (Prueba de Notificación)

• Escenario: Dentro del contenedor Docker en ejecución.
• Comando:

  curl "http://host.docker.internal:8088/?message=Hola+desde+Docker&sender=Docker&status=success"

• Para qué sirve: Envía la solicitud HTTP desde dentro del contenedor a la máquina host, la cual reproduce la alerta sonora y visual en tu pantalla y altavoces locales.

---

Caso B: Conexiones a Servidores Remotos (SSH)

Este caso aplica si el entorno donde corre tu IA se encuentra en un servidor remoto de desarrollo en la nube o en otra máquina física a la que te conectas por SSH.

Paso 1

• Escenario: En tu ordenador físico local (tu portátil/PC de uso personal).
• Comando:

  ianotifier listen 8088 127.0.0.1

• Para qué sirve: Arranca el servidor de escucha en tu máquina física (escuchando únicamente de forma local en 127.0.0.1 por seguridad).

Paso 2

• Escenario: En tu ordenador físico local al conectarte por SSH al servidor remoto.
• Comando:

  ssh -R 8088:127.0.0.1:8088 usuario@host_remoto

• Para qué sirve: Establece la conexión SSH creando un túnel reverso. Cualquier petición que el servidor remoto haga a su propio puerto 8088 (localhost remoto) se redirigirá de manera segura a tu puerto 8088 en tu portátil local.

Paso 3 (Prueba de Notificación)

• Escenario: Dentro de la sesión SSH en el servidor remoto.
• Comando:

  ianotifier --target ssh "Mensaje enviado por SSH"

• Para qué sirve: Envía el aviso detectando el puerto local 8088 en el host remoto (provisto por el túnel SSH). La notificación viaja por el túnel y suena físicamente en tu ordenador local.

---

🧪 Simulación de Pruebas Locales de SSH (Sin servidor externo)

Si deseas validar el comportamiento del túnel SSH localmente sin un servidor remoto real, sigue estos pasos:

1. Escenario: En una terminal de tu máquina local (Servidor).

   • Comando:

     ianotifier listen 8088 127.0.0.1

   • Para qué sirve: Levanta el microservidor HTTP de escucha en localhost.

2. Escenario: En otra terminal de tu máquina local (Cliente).

   • Comando:

     ianotifier --target ssh "Mensaje simulado por túnel SSH"

   • Para qué sirve: Envía la notificación simulando la existencia de un túnel SSH activo en el puerto 8088, permitiéndote verificar que el cliente y el servidor se comunican correctamente en red.

---

🔊 Personalización

El archivo de configuración se crea automáticamente en tu home tras el primer uso: ~/.config/ianotifier/config.json

Puedes abrirlo para personalizar:

• speech_language: Idioma por defecto (es o en).
• speech_voice: Voz por defecto de speech-dispatcher (female1, male1, etc.).
• ai_profiles: Personalizar los tonos, el tono de voz (pitch_shift) y la velocidad (rate_shift) para cada IA según su nombre (sender).

---

🧪 Pruebas Rápidas (CLI)

# Probar autodetección español (voz femenina de Antigravity + tono arpa ascendente)
ianotifier --sender "Antigravity" "He finalizado el refactor del código y todo funciona perfectamente."

# Probar autodetección inglés (voz masculina de Claude + tono de campana)
ianotifier --sender "Claude" "I have completed compiling the project."

# Probar alerta de error (sonido grave doble + notificación visual roja de alta prioridad)
ianotifier --sender "Claude" --status "error" "Error al ejecutar los tests unitarios."