Un desarrollador crea una mascota para Claude Code que patalea mientras el asistente espera una respuesta

Una situación conocida: le encarga a Claude Code una tarea grande, cambia a la ventana de al lado y un cuarto de hora después descubre que el agente lleva rato detenido en la pregunta «¿puedo ejecutar este comando?». La notificación del sistema de Windows sí apareció, claro, pero se mostró cinco segundos en una esquina de la pantalla mientras usted miraba hacia otro lado. El autor de un artículo en Habr resolvió el problema de forma radical: creó una mascota imposible de pasar por alto.

La mascota es un pequeño personaje naranja. Primero asoma por la esquina inferior derecha. Si se la ignora, sale entera, se pone roja y patalea sobre la barra de tareas hasta que usted vuelve. Es un envoltorio simpático, pero lo más útil es la parte de ingeniería: cómo saber de forma fiable que el asistente está esperando algo.

Cómo detectar el momento de espera

En la versión de terminal de Claude Code todo es sencillo gracias a los hooks. En ~/.claude/settings.json se puede definir un comando que se ejecuta con un evento concreto y recibe por stdin un JSON con los detalles. Para esta tarea sirve el evento Notification. El comando envía el contenido de stdin con curl al servidor HTTP local de la mascota (127.0.0.1:47821). La cola || exit 0 hace que, si la mascota no está en marcha, el hook termine en silencio con código cero y Claude Code no muestre un error en cada evento. Además, el servidor descarta las peticiones con cabecera Origin, para que una página web cualquiera no pueda llamar al puerto local.

Con la aplicación de escritorio de Claude (pestaña Code) la cosa se complica: cuando pide un permiso o plantea una pregunta, no envía el evento Notification. En el terminal todo funcionaba; en el escritorio, la mascota permanecía en silencio. Hubo que suscribirse también a PermissionRequest y a PreToolUse con el matcher AskUserQuestion|ExitPlanMode, para capturar las preguntas y la aprobación del plan. Opcionalmente existe Stop, que se dispara tras cada respuesta. La propia mascota registra los hooks: antes hace una copia de seguridad de settings.json (se conservan las cinco últimas) y no toca las entradas ajenas.

Hay un matiz: las sesiones ya abiertas pueden no recoger los nuevos hooks hasta reiniciarse. Por eso se añadió una segunda fuente de señal: la base de notificaciones de Windows. El sistema escribe cada aviso en el archivo SQLite wpndatabase.db. Una vez por segundo, la mascota lo abre en modo lectura y busca registros de la aplicación con el patrón Claude_*!Claude. El módulo node:sqlite, integrado en Node, evita dependencias nativas, y el método funciona incluso con Claude ya en ejecución, sin inyectar nada en él.

Una ventana que se ve, pero no molesta

La segunda tarea es dibujar el overlay. Debe ser transparente, situarse sobre todas las ventanas (incluidas las de pantalla completa), no aparecer en la barra de tareas, no robar el foco y dejar pasar los clics. En Electron esto se resuelve casi por completo con opciones de BrowserWindow: frame: false, transparent: true, skipTaskbar, alwaysOnTop, focusable: false.

Un truco interesante es setIgnoreMouseEvents(true, { forward: true }). La ventana se vuelve transparente a los clics, pero la página sigue recibiendo los eventos de movimiento del ratón. Cuando el cursor entra en la mascota (mouseenter), los clics se reactivan; cuando sale, se desactivan. No hace falta calcular a mano la forma de la ventana.

Para saber si la ventana de Claude está activa y devolverla al primer plano, el autor usa koffi, que llama a funciones de user32.dll sin node-gyp. La ventana activa se consulta cada 300 ms y la carga es imperceptible.

Detalles que conviene copiar

Si la mascota y el aviso estándar de Windows aparecen a la vez, se produce un duplicado. Para evitarlo hay una opción que desactiva los banners solo para Claude mediante ShowBanner = 0 en el registro. Las entradas en el centro de notificaciones se mantienen, de modo que la base sigue llenándose y la mascota las ve. El valor anterior del ajuste se guarda y se restaura al desactivar la opción, al salir, al cerrar la sesión e incluso, tras una caída inesperada, en el siguiente arranque.

Entre los escollos de compilación que menciona el artículo: electron-builder sube los archivos en paralelo y a veces crea releases duplicados, por lo que en GitHub Actions el release se crea primero con gh release create y después se rellena. En la versión portable, process.execPath apunta a una carpeta temporal, así que para el arranque automático la ruta se toma de la variable PORTABLE_EXECUTABLE_FILE.

Qué hacer con esto

El proyecto es gratuito, con licencia MIT y para Windows. Si no piensa instalar la mascota, el patrón sigue siendo útil: el hook Notification junto con un receptor HTTP local es la forma mínima de conectar Claude Code con cualquier señal externa, ya sea un sonido, un teléfono o una bombilla inteligente. La limitación principal es que la solución depende de Windows y del formato interno de la base de notificaciones, que Microsoft no documenta como API. Para Claude de escritorio, esta fuente es solo de respaldo y puede romperse con una actualización del sistema. Para la versión de terminal bastan los hooks.