Arquitectura

aipager es un programa asyncio de un solo proceso que funciona en segundo plano. Une tres mundos: tu chat de Telegram, los procesos de Claude Code que ejecutas bajo dtach, y el sistema de hooks de Claude Code. Todo pasa por un único event loop: sin grupos de workers, sin base de datos, sin colas entre procesos.

Diagrama de piezas#

Todo lo del diagrama, menos Telegram, funciona en esta computadora. aipager también habla con algunos otros servidores: el túnel de Cloudflare de la Mini App (y GitHub, una vez, para su cloudflared), telegram.org para el script de la Mini App, la búsqueda de versiones cuando pides una actualización, la descarga del modelo de voz la primera vez que usas audios, y el destino de los informes de problemas cuando envías uno. Todos están en Modelo de seguridad → conexiones de red.

Cómo funciona el proceso#

Una sola llamada a asyncio.run en aipager/cli/daemon.py lo mueve todo. Dentro:

• TelegramBot (aipager/bot/): tiene un Application de python-telegram-bot. Recibe las actualizaciones de Telegram, las reparte a los manejadores de mensajes, botones y audios, y mantiene al día las tarjetas de actividad, la barra de estado fijada y las respuestas.
• HookReceiver (aipager/dtach/hook_receiver.py): abre un socket datagram de Unix en $XDG_RUNTIME_DIR/aipager.sock, lee el JSON que envían aipager-hook y aipager-statusline, y reparte el trabajo según su hook_event_name (o type, para los mensajes propios de aipager; mira eventos de hook).
• SessionMonitor (aipager/session_monitor.py): se despierta cada 2 s para revisar /tmp/claude-dtach-*.sock, poner al día las sesiones que encuentra con la lista de sesiones, y ejecutar los vigilantes: una tarjeta de actividad que dejó de avanzar, un mensaje que Claude Code nunca recibió, una solicitud de permiso sin noticias durante 5 minutos que la conversación guardada muestra como terminada (AIPAGER_INTERACTIVE_TIMEOUT), una tarea cuyo final no se vio.
• SessionRegistry (aipager/state.py): los objetos TrackedSession por nombre de sesión. Se guardan en ~/.claude/aipager-sessions.json (de forma atómica) al apagarse y cada vez que cambia algo que tiene que sobrevivir a un reinicio.
• Servidor de la Mini App (aipager/miniapp/server.py): una app aiohttp en 127.0.0.1 y el puerto MINIAPP_PORT (por defecto 8765), que mientras está activada (por defecto) llega a Telegram por un túnel de Cloudflare gestionado. Sirve el panel de /app.

Todo esto funciona como tareas en el mismo loop. Lo que lo bloquearía se ejecuta en hilos aparte: pasar audios a texto, crear y enviar un informe de problemas, buscar actualizaciones y planear reinicios, descargar el script de la Mini App y cloudflared, y la comprobación de autenticación al arrancar.

Orden de arranque#

De aipager/cli/daemon.py:

1. Pasa una configuración antigua (config.env, team.yaml) a aipager.yaml, una sola vez, y aparta los archivos viejos.
2. No arranca si otro aipager responde en el socket; luego toma el bloqueo de aipager (~/.local/share/aipager/daemon.lock).
3. Comprueba el token del bot con Telegram (getMe).
4. Arregla los archivos del propio Claude Code: añade cualquier hook de aipager o la línea de estado que falten en ~/.claude/settings.json, y responde las preguntas del primer arranque que un usuario de Telegram no podría responder (mira Modelo de seguridad).
5. SessionRegistry.load(): lee ~/.claude/aipager-sessions.json. Si el archivo no está o no se puede leer, empieza con la lista vacía.
6. Averigua la dirección de la Mini App (tu propia URL, o Tailscale), luego bot.start(): empieza a recibir actualizaciones.
7. HookReceiver.start(): borra un archivo de socket que haya quedado, lo abre y escucha.
8. bot.recover_sessions(): recupera las tarjetas y las solicitudes de las sesiones que estaban trabajando o esperando cuando aipager se detuvo (mira comandos → respuestas).
9. SessionMonitor.start(): empieza el tic de 2 s.
10. Arranca el servidor de la Mini App, luego el túnel (si no pusiste una URL propia), y se publican los botones 📱 App.
11. aipager espera señales: SIGINT o SIGTERM lo detienen, SIGUSR1 vuelve a cargar los chats y las reglas (uso en equipo → recargar la configuración sin reiniciar).

Orden de apagado#

1. SIGINT o SIGTERM activan el evento stop.
2. Un /update en curso tiene un poco de margen y luego se detiene su instalador (mira comandos → actualizar).
3. registry.save().
4. Se detiene el túnel y luego el servidor de la Mini App.
5. session_monitor.stop(), hook_receiver.stop() (cierra el socket y borra su archivo).
6. bot.stop(): cancela las animaciones y detiene el Application.
7. Otra vez registry.save(), por si una tarjeta seguía enviándose.

El reinicio que se pide desde Telegram depende de que todo este camino termine antes de que el sustituto abra el socket. Lo que ves tú está en comandos del bot → reiniciar.

Dónde están los archivos y los sockets#

Además de esto, aipager crea una carpeta nueva para una sesión cuando se la pides (Nueva carpeta en /new o en la Mini App), y los instaladores y el modelo de voz escriben sus propios archivos cuando actualizas o usas la voz. Todo está bajo tu carpeta personal, bajo /tmp, o junto al socket de control. aipager nunca toma más permisos; mira Modelo de seguridad.

Una instancia aislada (para pruebas)#

Pon AIPAGER_INSTANCE_DIR en una carpeta absoluta que sea tuya y todos los archivos compartidos de la tabla de arriba se mueven ahí: el socket de control (y los sockets de respuesta, los archivos de señal de los límites de velocidad y la marca de cambio de modelo que están a su lado), los sockets claude-dtach-*, los archivos claude-policy-*, claude-notes-*, claude-status-* y claude-reply-*, el archivo del mínimo de seguridad, la carpeta de descargas aipager-files y el log del reinicio que aipager hace por su cuenta. Las sesiones que arranca la instancia heredan el ajuste, así que sus hooks solo hablan con esa instancia, y las reglas de seguridad protegen igual los archivos movidos. La instancia no lee el .env de un checkout.

Los archivos bajo tu carpeta personal no se mueven, así que apunta también HOME a otra carpeta. aipager start se niega a arrancar si la carpeta de la instancia está puesta y HOME es tu carpeta personal real, si la carpeta no es una ruta absoluta a una carpeta tuya, o si es demasiado larga para la ruta de un socket.

/update y /restart no quedan aislados: actúan sobre el paquete aipager instalado y el servicio aipager.service, así que nunca los envíes a una instancia de prueba.

AIPAGER_TELEGRAM_API_BASE (por ejemplo http://127.0.0.1:41234) envía todas las peticiones a la Bot API y las descargas de archivos a esa dirección en lugar de https://api.telegram.org. Tiene que ser esta computadora (localhost o una dirección loopback) salvo que pongas AIPAGER_TELEGRAM_API_ALLOW_REMOTE=1, para que un error de escritura no pueda enviar el token del bot a otro sitio.

Los dos ajustes existen para que las pruebas de punta a punta puedan ejecutar un segundo aipager contra un Telegram de imitación local, junto al tuyo de verdad. Sin ninguno de los dos, todas las rutas y direcciones son las de la tabla de arriba.

Por qué dtach#

dtach le da a cada sesión de Claude Code una PTY real sin atarla a una terminal que tenga que seguir abierta. aipager arranca una sesión con dtach -n y escribe en ella con dtach -p (mensajes, Escape, las teclas que responden un diálogo); nunca lee la pantalla, porque los hooks y la conversación guardada dicen lo que pasa. Puedes conectarte de forma interactiva desde cualquier shell con aipager session <name> para tener acceso directo. Esa conexión sigue a la sesión a través de un reinicio desde Telegram (/mode hacia o desde Modo Acceso total, /restart, Reiniciar): cuando el socket de la sesión desaparece, espera hasta 15 s a que vuelva el mismo socket y se reconecta sola. Si la sesión terminó de verdad, vuelves al shell después de la espera (Ctrl-C corta la espera antes). La conexión funciona con la tecla de desconexión de dtach apagada, así que Ctrl-\ llega a Claude; para salir, cierra la terminal o el panel de tmux y la sesión sigue en marcha.

El resultado: Claude Code funciona como si escribieras en una terminal, pero esa terminal puede ir y venir sin molestar a la sesión en marcha. aipager encuentra las sesiones revisando /tmp/claude-dtach-*.sock en cada tic de 2 s del vigilante. Una sesión encontrada pertenece al chat para el que se creó su nombre, y una creada en la terminal pertenece al chat privado del propietario en una instalación con chat privado y grupo.

Ver también#

• Eventos de hook: lo que llega por el socket de control.
• Comandos del bot: lo que llega desde Telegram.
• Modelo de seguridad: límite de permisos, secretos, auditoría.
• Solución de problemas: referencia de aipager doctor.