Claude Telegram Supercharged

Actualización directa para el plugin oficial del canal de Telegram de Claude Code: transcripción y respuestas de voz, historial y memoria SQLite, hilos de grupo, botones en línea, mensajes programados y un supervisor de daemon.

GitHub

116

Prueba este MCPPatrocinado

Documentación

El plugin oficial de Claude Code para Telegram es bueno. Este es mejor.

Primeros pasos • Características • Modo Agéntico • Referencia de Herramientas • Contribuciones

Claude Telegram Supercharged

Mejora directa del plugin oficial de Claude Code para Telegram. Instálalo una vez y obtén más de 15 funciones que el plugin oficial no tiene. Construido sobre el plugin oficial: todo funciona, solo que mejor.

2 minutos de instalación. Cero configuración. Tu bot y emparejamiento existentes siguen funcionando.

Instalación en una línea

Instala primero el plugin oficial (en Claude Code: /plugin install telegram@claude-plugins-official), luego:

curl -fsSL https://raw.githubusercontent.com/k1p1l0/claude-telegram-supercharged/master/install.sh | bash

Ejecútalo de nuevo en cualquier momento para actualizar. La guía completa está en Primeros pasos.

Seguridad: la única fuente oficial es github.com/k1p1l0/claude-telegram-supercharged. Este proyecto nunca distribuye descargas zip o exe. Las copias en otros lugares que ofrecen un archivo zip son malware; por favor no las ejecutes y repórtalas a GitHub.

Oficial vs Supercharged

	Plugin oficial	Supercharged
Texto, fotos, archivos, stickers	✅	✅
Respuestas formateadas, división de mensajes largos	✅	✅
Mensajes de voz	Archivo de audio crudo	✅ Transcritos (OpenAI, Groq, Deepgram o Whisper local)
Respuestas de voz	❌	✅ ElevenLabs
Progreso en vivo mientras Claude trabaja	❌	✅ Modo Agéntico
Historial y memoria que sobreviven reinicios	❌	✅ SQLite + archivo de memoria
Sabe a qué mensaje respondiste	❌	✅ Contexto de respuesta, citas, reenvíos
Preguntas con botones en línea	❌	✅ `ask_user`
Mensajes programados y recordatorios	❌	✅ También sincroniza con Recordatorios de Apple
Google Calendar	❌	✅
Demonio 24/7 con reinicio automático	❌	✅ Supervisor launchd
Enrutamiento de modelos (Haiku / Sonnet / Opus)	❌	✅
Respuestas largas como artículos de Telegraph	❌	✅
Aprobar solicitudes de permisos desde Telegram	✅	✅ Botones o "sí ", más una lista de aprobación automática

Características

Voz y Audio

Característica	Qué hace
🎤 Mensajes de voz	Habla con Claude. Cadena de respaldo de proveedores: OpenAI Whisper → Groq → Deepgram → whisper-cli local. Funciona desde tu teléfono mientras caminas.
🔊 Respuestas de voz (TTS)	Claude responde con mensajes de voz mediante ElevenLabs TTS. Formato nativo OGG/Opus. Respaldo automático a archivo de audio si la voz está restringida.
🎤 Transcripción automática	TODOS los mensajes de voz en chats grupales se transcriben, incluso sin mencionar al bot. Configurable mediante `autoTranscribe`.

Mensajes y Multimedia

Característica	Qué hace
📨 Mensajes reenviados	Contexto completo de reenvío preservado: Claude ve quién lo envió originalmente y desde qué chat/canal.
📦 Agrupación de mensajes	Reenvía 20+ mensajes a la vez: se recogen en un lote (debounce de 5s), se resumen automáticamente al instante, y luego Claude responde a toda la conversación en una sola respuesta.
📄 Soporte de documentos	Envía PDFs, DOCX, CSV, TXT, JSON: Claude descarga, lee y resume. Límite de tamaño de archivo de 10MB.
🎨 Autoescape MarkdownV2	Los caracteres especiales se escapan automáticamente en el servidor: Claude escribe texto natural, sin necesidad de escape manual de `\.`.
😎 Soporte de stickers y GIFs	Claude ve stickers y GIFs. Estáticos como imágenes, animados como collages de múltiples fotogramas.
📰 Vista instantánea de Telegraph	Investigaciones largas (3000+ caracteres) publicadas en telegra.ph como Vista Instantánea. Deshabilitado por defecto: opt-in mediante `TELEGRAPH_ENABLED=true`.

Conversaciones y Grupos

Característica	Qué hace
💬 Historial de mensajes	Almacén rotativo respaldado por SQLite. Claude tiene contexto entre reinicios. Herramientas `get_history` + `search_messages`.
🧠 Memoria de conversación	`/clean` guarda un resumen antes de limpiar. La memoria persiste entre sesiones. Claude nunca olvida.
🧵 Hilos de conversación	Sigue cadenas de respuestas en grupos, ve quién dijo qué, responde en el hilo correcto. Hasta 3 niveles de profundidad.
📋 Temas de foro	Los temas de foro de Telegram son totalmente compatibles. Cada tema aislado con `thread_id` persistente.
👥 Emparejamiento de grupos	Añade el bot al grupo, menciónalo, obtén el código de emparejamiento. Sin buscar IDs numéricos de chat.
🎯 Botones en línea	Herramienta `ask_user`: botones pulsables para confirmaciones y opciones.
👍 Estado de reacciones	👀 leído → 🔥 trabajando → 👍 hecho. Los mensajes de voz reciben ✍ para transcripción.

Demonio e Infraestructura

Característica	Qué hace
⚡ Enrutamiento de modelos de dos niveles	Enrutador configurable: Haiku (rápido, 200K), Sonnet (equilibrado, 1M) u Opus (profundo, 1M). Configura mediante `TELEGRAM_ROUTER_MODEL`. Las tareas complejas escalan automáticamente a Opus mediante subagentes (cambia el objetivo con `TELEGRAM_ESCALATION_MODEL`).
🛠 Modo Agéntico	Observa trabajar a Claude: "escribiendo…" todo el tiempo, más un mensaje en vivo "Trabajando… (Ns)" con las notas de Claude y cada llamada de herramienta mientras se ejecuta. La respuesta lo reemplaza en su lugar. `/verbose 0\|1\|2`, `/status`, `/new`. Detalles
🔄 Modo demonio	El supervisor reinicia automáticamente a Claude ante un fallo o reinicio de contexto. Memoria preservada, cero tiempo de inactividad.
🛡 Vigilante de contexto	Reinicio automático cuando el contexto supera el 50%, o después de 2 horas de actividad, para mantener las sesiones receptivas. El historial SQLite y la memoria sobreviven reinicios.
🔒 Bloqueo de instancia única	Archivo de bloqueo basado en PID evita instancias duplicadas del bot compitiendo por actualizaciones de Telegram.
🖥 Gestión del demonio	`/telegram:daemon start\|stop\|restart\|status\|logs`: ciclo de vida completo. `/telegram:monitor` para panel de salud con URL de control remoto.
⏰ Mensajes programados	Herramienta `schedule` para recordatorios y tareas recurrentes. Tipos "at" (una sola vez) y "every" (intervalo). Persiste entre reinicios.
📅 Google Calendar	Consulta el calendario, crea eventos, resúmenes diarios desde Telegram. Soporte multi-cuenta. Proactivo: Claude usa el contexto del calendario al responder.
📸 Capturas de pantalla sin interfaz	Captura de páginas basada en Playwright: funciona en modo demonio donde Chrome no está disponible.
✅ Validación de reacciones	Lista blanca de emojis en el cliente previene errores crípticos de la API de Telegram.
🔒 Protección contra inyección de shell	Todas las llamadas a subprocesos usan `spawnSync` con argumentos de matriz. Sin interpretación de shell.
📊 Caché inteligente	Voz/audio en caché entre middleware y manejadores. Sin dobles descargas ni transcripciones.

Primeros pasos

Flujo de emparejamiento predeterminado para un bot DM de un solo usuario. Consulta ACCESS.md para grupos y configuraciones multi-usuario.

Requisitos previos

Bun: el servidor MCP se ejecuta en Bun. Instala con curl -fsSL https://bun.sh/install | bash.

1. Crea un bot con BotFather

Abre un chat con @BotFather en Telegram y envía /newbot. BotFather pide dos cosas:

Nombre: el nombre visible que se muestra en los encabezados del chat (cualquier cosa, puede contener espacios)
Nombre de usuario: un identificador único que termina en bot (por ejemplo, my_assistant_bot). Este se convierte en el enlace de tu bot: t.me/my_assistant_bot.

BotFather responde con un token que se ve así: 123456789:AAHfiqksKZ8...: ese es el token completo, cópialo incluyendo el número inicial y los dos puntos.

2. Instala el plugin oficial

Estos son comandos de Claude Code: ejecuta claude para iniciar una sesión primero.

/plugin install telegram@claude-plugins-official

3. Aplica la versión supercharged

Clona este repositorio e instala tanto el servidor supercharged como el supervisor del demonio:

git clone https://github.com/k1p1l0/claude-telegram-supercharged.git
cp claude-telegram-supercharged/server.ts ~/.claude/plugins/cache/claude-plugins-official/telegram/$(ls ~/.claude/plugins/cache/claude-plugins-official/telegram/ | sort -V | tail -1)/server.ts
mkdir -p ~/.claude/scripts
cp claude-telegram-supercharged/supervisor.ts ~/.claude/scripts/telegram-supervisor.ts
cp claude-telegram-supercharged/scripts/claude-daemon-wrapper.exp ~/.claude/scripts/claude-daemon-wrapper.exp
chmod +x ~/.claude/scripts/claude-daemon-wrapper.exp
cp claude-telegram-supercharged/scripts/telegram-progress-hook.ts ~/.claude/scripts/telegram-progress-hook.ts

4. Dale el token al servidor

/telegram:configure 123456789:AAHfiqksKZ8...

Escribe TELEGRAM_BOT_TOKEN=... en ~/.claude/channels/telegram/.env. También puedes escribir ese archivo a mano, o configurar la variable en tu entorno de shell: el shell tiene prioridad.

5. Relanza con el indicador de canal

El servidor no se conectará sin esto: sal de tu sesión e inicia una nueva:

claude --channels plugin:telegram@claude-plugins-official

O usa el supervisor del demonio para operación siempre activa con reinicio automático y reinicio de contexto desde Telegram (consulta Modo demonio):

bun ~/.claude/scripts/telegram-supervisor.ts

6. Empareja

Con Claude Code ejecutándose desde el paso anterior, envía un DM a tu bot en Telegram: responde con un código de emparejamiento de 6 caracteres. Si el bot no responde, asegúrate de que tu sesión se ejecute con --channels. En tu sesión de Claude Code:

/telegram:access pair <code>

Tu siguiente DM llega al asistente.

A diferencia de Discord, no hay paso de invitación al servidor: los bots de Telegram aceptan DMs inmediatamente. El emparejamiento maneja la búsqueda de ID de usuario para que nunca toques IDs numéricos.

7. Asegúralo

El emparejamiento es para capturar IDs. Una vez que estés dentro, cambia a allowlist para que los desconocidos no reciban respuestas con códigos de emparejamiento. Pídele a Claude que lo haga, o /telegram:access policy allowlist directamente.

Actualización

Importante: El plugin oficial se actualiza automáticamente y sobrescribirá tu server.ts supercharged. Cuando el bot deje de funcionar repentinamente después de una actualización, esta es la razón.

La forma más rápida de actualizar (también después de una actualización del plugin oficial) es volver a ejecutar el instalador de una línea. Para hacerlo a mano:

Cuando el plugin oficial se actualice (verifica nuevos directorios de versión en ~/.claude/plugins/cache/claude-plugins-official/telegram/):

cd claude-telegram-supercharged
git pull
# Find the current version (e.g. 0.0.4)
PLUGIN_VERSION=$(ls ~/.claude/plugins/cache/claude-plugins-official/telegram/ | sort -V | tail -1)
echo "Updating to version: $PLUGIN_VERSION"
cp server.ts ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/server.ts
cp supervisor.ts ~/.claude/scripts/telegram-supervisor.ts
# Copy skills
cp -r skills/* ~/.claude/plugins/cache/claude-plugins-official/telegram/$PLUGIN_VERSION/skills/
# Copy scripts
cp scripts/claude-daemon-wrapper.exp ~/.claude/scripts/claude-daemon-wrapper.exp
cp scripts/telegram-progress-hook.ts ~/.claude/scripts/telegram-progress-hook.ts

Luego reinicia tu demonio o sesión de Claude Code.

Herramientas Expuestas al Asistente

Herramienta	Propósito
`reply`	Enviar a un chat. Toma `chat_id` + `text`, opcionalmente `reply_to` (ID de mensaje) para hilos nativos, `files` (rutas absolutas) para archivos adjuntos, y `parse_mode` (MarkdownV2/HTML/plain, por defecto MarkdownV2). Las imágenes (`.jpg`/`.png`/`.gif`/`.webp`) se envían como fotos con vista previa en línea; otros tipos se envían como documentos. Máximo 50MB cada uno. Divide texto automáticamente; los archivos se envían como mensajes separados después del texto. Devuelve el/los ID(s) del mensaje enviado.
`react`	Añadir una reacción emoji a un mensaje por ID. Solo se acepta la lista fija de Telegram (👍 👎 ❤ 🔥 👀 🎉 😂 🤔 etc.). También se usa para indicadores de estado (👀 leído → 👍 hecho).
`edit_message`	Editar un mensaje que el bot envió previamente. Soporta `parse_mode` (MarkdownV2/HTML/plain). Útil para actualizaciones de progreso "trabajando..." → resultado. Solo funciona en mensajes propios del bot.
`ask_user`	Enviar una pregunta con botones de teclado en línea y esperar la elección del usuario. Toma `chat_id`, `text`, `buttons` (array de etiquetas), opcionalmente `parse_mode` y `timeout` (por defecto 120s). Devuelve la etiqueta del botón pulsado.
`get_history`	Recuperar el historial reciente de mensajes de un chat. Toma `chat_id`, opcionalmente `limit` (por defecto 50, máximo 200), opcionalmente `before` (marca de tiempo unix para paginación). Devuelve mensajes formateados con marcas de tiempo, remitentes y contenido.
`search_messages`	Buscar en el historial de mensajes por patrón de texto. Toma `chat_id`, `query` (coincidencia de subcadena), opcionalmente `limit` (por defecto 20, máximo 100). Devuelve mensajes coincidentes.
`clear_history`	Borrar todo el historial de mensajes de un chat. Siempre confirma primero con `ask_user`, y llama a `save_memory` antes de borrar para preservar el contexto. Pasa `restart_context: true` para señalar al daemon supervisor que reinicie Claude para un reinicio completo del contexto.
`save_memory`	Guardar un resumen de conversación en memoria persistente. Se carga en las instrucciones de Claude en cada inicio. Úsalo antes de `clear_history` para que el contexto sobreviva entre sesiones.
`create_telegraph_page`	Publicar contenido de formato largo en Telegraph (telegra.ph) y devolver una URL. Telegram lo renderiza como Instant View — un lector de artículos nativo. Toma `title`, `content` (Markdown), opcionalmente `author_name` y `author_url`. Crea automáticamente una cuenta de Telegraph en el primer uso.

Eventos Entrantes

Evento	Descripción
Mensaje de texto	Reenviado a Claude como notificación de canal con `chat_id`, `message_id`, `user`, `ts`.
Foto	Descargada a la bandeja de entrada, la ruta se incluye en la notificación para que Claude pueda `Read`.
Reacción emoji	Cuando un usuario reacciona a un mensaje del bot, Claude recibe una notificación con `event_type: "reaction"`, el emoji y el `message_id`. Úsalo como retroalimentación ligera.
Mensaje de voz	Descargado a la bandeja de entrada como `.ogg`, transcrito automáticamente por el servidor si whisper está instalado. La transcripción reemplaza "(mensaje de voz)" en el texto de la notificación. La ruta de audio aún se incluye como `audio_path`.
Archivo de audio	Archivos de audio reenviados (`.mp3`, etc.) descargados a la bandeja de entrada, la ruta se incluye como `audio_path`.
Sticker	`.webp` estático pasado directamente como `image_path`. Los stickers animados (`.tgs`) y de video (`.webm`) se convierten en collage de múltiples fotogramas. El emoji y el nombre del paquete se incluyen en el texto.
GIF / Animación	Descargado y convertido a un collage horizontal de múltiples fotogramas para que Claude pueda ver el contenido de la animación.

Los mensajes entrantes activan automáticamente un indicador de escritura — Telegram muestra "botname está escribiendo..." mientras el asistente trabaja en una respuesta.

Mensajes de Voz y Audio

Los mensajes de voz y archivos de audio se descargan a ~/.claude/channels/telegram/inbox/ y se transcriben automáticamente por el servidor. El texto de la transcripción reemplaza "(mensaje de voz)" en la notificación, por lo que Claude recibe el texto hablado directamente.

Piénsalo como Wispr Flow para Claude Code. Abre Telegram, mantén presionado el botón de micrófono, di "refactoriza el middleware de autenticación para usar JWT" — Claude lo recibe como texto y comienza a trabajar. Sin escribir, sin necesidad de aplicación de escritorio, funciona desde tu teléfono.

Configuración de Transcripción

El servidor intenta métodos de transcripción en este orden:

OpenAI Whisper API (recomendado) — más rápido, mayor calidad, no bloqueante. Configura tu clave API en ~/.claude/channels/telegram/.env:
```
OPENAI_API_KEY=sk-proj-...
```
Usa whisper-1 por defecto ($0.006/min). Puedes cambiar a un modelo diferente:
```
OPENAI_WHISPER_MODEL=gpt-4o-transcribe
```
No se necesita instalación local. El método de transcripción activo se registra al inicio.

whisper.cpp (respaldo local) — brew install whisper-cpp. Puerto C++ rápido, funciona completamente sin conexión. Requiere un archivo de modelo:

# Download the small multilingual model (465MB, good quality/speed balance)
mkdir -p /usr/local/share/whisper-cpp/models
curl -L -o /usr/local/share/whisper-cpp/models/ggml-small.bin \
  "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-small.bin"

openai-whisper (respaldo local) — pip install openai-whisper. Basado en Python, más lento pero también funciona sin conexión.
Sin transcriptor — los mensajes de voz aún se descargan y el audio_path se incluye en la notificación, pero no se proporciona transcripción.

Las opciones locales (2 y 3) requieren ffmpeg (brew install ffmpeg) para la conversión de formato de audio. Si tienes una clave API de OpenAI, la opción 1 es recomendada — es asíncrona (no bloquea el bucle de eventos), más rápida y más precisa.

Auto-transcripción en el historial

Cuando autoTranscribe está habilitado (por defecto), el servidor transcribe todos los mensajes de voz/audio en chats grupales — incluso aquellos que no mencionan al bot. Esto significa que get_history y el contexto auto-inyectado siempre muestran el texto hablado (prefijado con 🎤) en lugar de [voice]. Claude obtiene contexto conversacional completo, incluyendo lo que la gente dijo en mensajes de voz.

Para deshabilitar (por ejemplo, para ahorrar CPU en grupos ocupados):

/telegram:access set autoTranscribe false

Para re-habilitar:

/telegram:access set autoTranscribe true

Telegraph (Artículos Instant View)

Claude puede publicar contenido de formato largo en Telegraph y enviarlo como enlaces Instant View en Telegram — un lector de artículos nativo a pantalla completa. Telegraph está deshabilitado por defecto porque las publicaciones son accesibles públicamente por URL.

Para habilitar, añade a ~/.claude/channels/telegram/.env:

TELEGRAPH_ENABLED=true

Cuando está habilitado, Claude solo usa Telegraph para contenido realmente largo (3000+ caracteres con múltiples secciones) — informes de investigación, análisis completos, guías detalladas. Las respuestas regulares siempre permanecen en el chat.

Cuando está deshabilitado (por defecto):

La herramienta create_telegraph_page está oculta para Claude
Claude envía todo el contenido directamente en mensajes de chat
El prompt del sistema no menciona Telegraph

Requiere reiniciar el servidor MCP para que surta efecto.

Memoria de Conversación

Cuando borras el historial de chat, Claude primero guarda un resumen corto en ~/.claude/channels/telegram/data/memory.md. Este archivo se carga en las instrucciones de Claude en cada inicio — por lo que el contexto de sesiones anteriores nunca se pierde por completo.

Los resúmenes están fechados y etiquetados con el ID del chat
El archivo se auto-comprime cuando supera los 10,000 caracteres (la mitad más antigua se recorta)
Funciona a través de /clear y reinicios de Claude Code

Modo Daemon

El plugin incluye un script supervisor (supervisor.ts) que ejecuta Claude Code como un proceso hijo gestionado. Maneja:

Auto-reinicio en caso de fallo — retroceso exponencial (1s, 2s, 4s... hasta 30s), se restablece después de 60s de tiempo de actividad estable
Restablecimiento de contexto desde Telegram — di "borra todo" en Telegram, Claude guarda la memoria, borra el historial, y el supervisor reinicia Claude con una sesión nueva. Cero tiempo de inactividad, memoria preservada.
Protocolo de archivo de señal — el servidor MCP escribe ~/.claude/channels/telegram/data/restart.signal, el supervisor lo detecta dentro de 500ms, espera 3 segundos para que Claude termine de enviar respuestas, luego mata y regenera

Uso

Si seguiste los pasos de Getting Started, el supervisor ya está instalado en ~/.claude/scripts/telegram-supervisor.ts. Solo ejecuta:

bun ~/.claude/scripts/telegram-supervisor.ts

Las banderas adicionales se reenvían a Claude:

bun supervisor.ts --effort high

El supervisor genera Claude con --channels plugin:telegram@claude-plugins-official --dangerously-skip-permissions por defecto.

Modo Agéntico

En modo daemon puedes ver a Claude trabajar, como lo harías en la terminal:

You: Read the README and check package.json for the scripts
Bot: Working... (14s)
     💬 Reading the README to see the install steps.
     💻 Bash: Read README intro
     💬 Now checking package.json for the scripts.
     📖 Read: package.json
     ✍️ Writing…
Bot: [the answer replaces the Working message]

Indicador de escritura durante todo el tiempo que Claude trabaja, en cada nivel de verbosidad. Se pausa mientras una pregunta de ask_user espera tu respuesta.
Mensaje de trabajo una vez que un turno dura más de 2.5 segundos, por lo que las respuestas rápidas nunca lo reciben. Muestra las notas cortas de Claude (💬), cada llamada de herramienta cuando comienza (Read, Edit, Bash, Grep, WebFetch, Agent, Skill, herramientas MCP, etc.), y lo que Claude está haciendo ahora: 💭 Thinking… después de que una herramienta devuelve, ✍️ Writing… una vez que está produciendo salida.
La respuesta reemplaza el mensaje de trabajo en su lugar. Telegram no envía notificaciones push para ediciones, por lo que estas respuestas llegan silenciosamente. Respuestas rápidas, respuestas de múltiples partes, archivos y respuestas con cita llegan como mensajes normales.
El mensaje de trabajo siempre es el mensaje más nuevo. Si escribes mientras Claude trabaja, se mueve debajo de tu mensaje. Las herramientas propias de Telegram (responder, reaccionar, etc.) y ToolSearch no se listan.
Solo DMs, porque las líneas de herramientas pueden mostrar rutas de archivos y comandos.

Comando	Qué hace
`/verbose 0`	Sin mensaje de trabajo: solo indicador de escritura y la respuesta
`/verbose 1`	Notas y nombres de herramientas con un objetivo corto (por defecto)
`/verbose 2`	Notas más largas y entradas completas de herramientas (comandos, rutas, URLs)
`/status`	Trabajando o inactivo, tiempo transcurrido, conteo de herramientas, tiempo de actividad, modelo del router
`/new`	Sesión nueva de Claude a través del supervisor. La memoria y el historial se conservan.

Los comandos responden a usuarios en lista blanca en DMs. /verbose se almacena por chat.

Cómo funciona. El supervisor pasa scripts/telegram-progress-hook.ts a Claude como un hook de PreToolUse, PostToolUse y Stop a través de --settings, por lo que nunca se ejecuta en tus sesiones interactivas. El hook agrega cada evento a ~/.claude/channels/telegram/data/progress.jsonl, y el servidor sigue ese archivo y edita el mensaje de trabajo (como máximo una edición por cada 1.5 segundos). Las notas de Claude y la fase de pensamiento/escritura provienen de la transcripción de la sesión. Las instrucciones del servidor piden a Claude escribir una oración corta antes de cada llamada de herramienta.

Configuración (entorno del supervisor): TELEGRAM_VERBOSE establece el nivel por defecto (1). TELEGRAM_AGENTIC_MODE=off desactiva el hook.

Cómo funciona el restablecimiento de contexto

El usuario envía "borra todo" en Telegram
Claude confirma mediante botones en línea (ask_user)
Claude guarda un resumen de conversación (save_memory)
Claude envía una respuesta de confirmación a Telegram
Claude llama a clear_history con restart_context: true
El servidor MCP escribe restart.signal con un retraso de 3 segundos
El supervisor detecta el archivo, espera a que Claude termine, luego mata el proceso
El supervisor genera una sesión nueva de Claude — memory.md se carga en las instrucciones automáticamente

Siempre activo con launchd (macOS)

Ejecutar el supervisor en una terminal (o tmux/screen) funciona para sesiones rápidas, pero tiene un problema fundamental en macOS: el sistema suspende los procesos en segundo plano agresivamente. Cuando cierras la tapa, cambias de usuario, o el Mac se duerme, macOS envía SIGSTOP a los procesos de terminal — tu bot se queda en silencio hasta que abres la tapa de nuevo. tmux/screen no ayudan porque se ejecutan en el espacio de usuario y también se suspenden.

launchd es el gestor de procesos nativo de Apple — el mismo sistema que mantiene Spotlight, Time Machine e iCloud funcionando. Opera a nivel del sistema operativo, fuera de cualquier sesión de terminal, por lo que:

Sobrevive al cierre de la tapa — el proceso sigue ejecutándose cuando cierras tu MacBook (con energía)
Sobrevive al cierre de sesión — permanece activo incluso si cierras sesión de tu usuario
Auto-inicia al arrancar — no necesitas recordar iniciarlo después de un reinicio
Auto-reinicia en caso de fallo — si el supervisor muere inesperadamente, launchd lo trae de vuelta
Permanece despierto — envolvemos el supervisor con caffeinate -s para prevenir el sueño del sistema

Configuración

Crea ~/Library/LaunchAgents/com.user.claude-telegram.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.claude-telegram</string>

    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/caffeinate</string>
        <string>-s</string>
        <string>/path/to/bun</string>
        <string>/Users/YOU/.claude/scripts/telegram-supervisor.ts</string>
    </array>

    <key>RunAtLoad</key>
    <true/>

    <key>KeepAlive</key>
    <true/>

    <key>StandardOutPath</key>
    <string>/Users/YOU/.claude/channels/telegram/data/supervisor-stdout.log</string>

    <key>StandardErrorPath</key>
    <string>/Users/YOU/.claude/channels/telegram/data/supervisor-stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/path/to/bun/dir:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    </dict>

    <key>WorkingDirectory</key>
    <string>/Users/YOU</string>

    <key>ProcessType</key>
    <string>Background</string>

    <key>ThrottleInterval</key>
    <integer>10</integer>
</dict>
</plist>

Reemplaza /path/to/bun con tu ruta de bun (which bun) y /Users/YOU con tu directorio de inicio.

No sobrescribas HOME en el plist. El wrapper ejecuta claude desde ~/.claude-telegram-daemon, porque un cwd de $HOME hace que Claude Code elimine el plugin de telegram. Para usar otro directorio, establece TELEGRAM_DAEMON_CWD en EnvironmentVariables. Si el daemon se comporta mal, consulta Solución de problemas del daemon.

Importante: Tanto RunAtLoad como KeepAlive deben establecerse en <true/> para una operación sin intervención. RunAtLoad inicia el daemon automáticamente al iniciar sesión/arrancar. KeepAlive le dice a launchd que reinicie el proceso si sale inesperadamente. Establecer cualquiera de ellos en <false/> significa que necesitarás iniciar el daemon manualmente o no se recuperará de fallos.

Gestión del daemon

Iniciar el daemon:

launchctl load ~/Library/LaunchAgents/com.user.claude-telegram.plist

Detener el daemon:

launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist

Comprobar si está en ejecución:

launchctl list | grep claude-telegram

Un daemon en ejecución muestra su PID en la primera columna. Un 0 en la columna de estado significa que salió limpiamente; un valor distinto de cero significa que falló (launchd lo reiniciará).

Ver registros:

tail -f ~/.claude/channels/telegram/data/supervisor-stderr.log

Reiniciar (recargar configuración después de editar el plist):

launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist
launchctl load ~/Library/LaunchAgents/com.user.claude-telegram.plist

Eliminar por completo (detener + borrar):

launchctl unload ~/Library/LaunchAgents/com.user.claude-telegram.plist
rm ~/Library/LaunchAgents/com.user.claude-telegram.plist

Monitoreo del daemon

Usa la habilidad de monitor integrada desde cualquier sesión de Claude Code:

/telegram:monitor

Muestra un panel en vivo: estado del proceso para todos los componentes, estado de launchd, registros recientes, salud de MCP, URL de control remoto (observa el daemon en vivo en tu navegador) y estado del archivo de bloqueo.

También puedes monitorear manualmente:

# Live supervisor logs
tail -f ~/.claude/channels/telegram/data/supervisor-stderr.log

# Quick alive check
ps aux | grep "channels.*telegram" | grep -v grep && echo "ALIVE" || echo "DEAD"

# Find the remote control URL (open in browser to watch the daemon live)
strings ~/.claude/channels/telegram/data/supervisor-stdout.log | grep "session_" | tail -1

Cómo funcionan juntas las capas

launchd (OS-level)
  └── caffeinate -s (prevents system sleep)
        └── supervisor.ts (manages Claude lifecycle)
              └── claude --channels plugin:telegram (the actual bot)

launchd asegura que el árbol de procesos esté siempre vivo
caffeinate mantiene la Mac despierta mientras el proceso se ejecuta
supervisor maneja reinicios específicos de Claude (restablecimiento de contexto, recuperación de fallos con retroceso)
Claude se ejecuta como un proceso hijo gestionado con el canal de Telegram

Nota: caffeinate -s evita el sueño solo cuando está conectado a la corriente. Con batería y la tapa cerrada, macOS eventualmente dormirá de todos modos. Para un tiempo de actividad real de 24/7 con batería, considera ejecutarlo en un servidor en su lugar.

Chats de grupo y subprocesos de conversación

El plugin admite chats de grupo con subprocesos de conversación inteligentes: Claude puede seguir cadenas de respuestas, ver quién dijo qué y responder en el hilo correcto.

Configuración

1. Desactiva el modo de privacidad en BotFather

Por defecto, los bots de Telegram en grupos solo ven comandos y mensajes que los mencionan. Para un seguimiento completo de hilos, desactiva el modo de privacidad:

Abre @BotFather en Telegram
Envía /mybots → selecciona tu bot
Bot Settings → Group Privacy → Turn off

Si prefieres mantener el modo de privacidad activado, el bot seguirá funcionando; simplemente no verá mensajes que no lo mencionen, por lo que el seguimiento de hilos será incompleto.

2. Añade el bot a un grupo

Añade tu bot a cualquier grupo de Telegram como un miembro normal.

3. Vincula el grupo (automático)

Solo envía un mensaje en el grupo mencionando a tu bot (por ejemplo, @your_bot hello). El bot responde con un código de vinculación de 6 caracteres, el mismo flujo que la vinculación por DM:

/telegram:access pair <code>

Eso es todo. El grupo se registra automáticamente con requireMention: true (el bot solo responde cuando se le menciona o se le responde).

Para permitir que responda a todos los mensajes:

/telegram:access group update -100XXXXXXXXXX requireMention false

Alternativa manual: Si ya conoces el ID numérico del grupo (comienza con -100...), puedes registrarlo directamente con /telegram:access group add -100XXXXXXXXXX. Formas de encontrar el ID: revisa los registros de stderr del bot, abre web.telegram.org (el ID está en la URL) o reenvía un mensaje del grupo a @RawDataBot.

4. Reinicia Claude Code

claude --channels plugin:telegram@claude-plugins-official

Cómo funcionan los subprocesos

Cuando alguien responde a un mensaje en el grupo, Claude recibe reply_to_text y reply_to_user mostrando a qué se respondió
El plugin rastrea hasta 200 mensajes por chat (TTL de 4 horas) y recorre cadenas de respuestas hasta 3 niveles de profundidad, proporcionando thread_context en la notificación
Los mensajes enviados por el propio Claude también se rastrean, por lo que las cadenas de respuestas funcionan de extremo a extremo
Claude enhebra automáticamente sus respuestas al mensaje que las desencadenó

Temas del foro

Si tu supergrupo tiene Topics habilitados, el plugin reenvía thread_id (el message_thread_id de Telegram) y lo pasa a las respuestas, manteniendo las conversaciones en su tema de Foro correcto automáticamente. Los IDs de tema se persisten en SQLite para que el contexto se conserve entre reinicios.

Control de acceso

Documentación completa de control de acceso en ACCESS.md: políticas de DM, grupos, detección de menciones, configuración de entrega, comandos de habilidades y el esquema access.json.

Referencia rápida: La política predeterminada es pairing: tanto los DM como los grupos usan el flujo de vinculación. Para DM, envía un mensaje al bot para obtener un código. Para grupos, añade el bot y menciónalo para obtener un código. Luego /telegram:access pair <code> aprueba cualquiera de los dos. ackReaction solo acepta la lista blanca de emojis fija de Telegram.

Aprobaciones de permisos

Si tu sesión no omite permisos, Claude Code envía cada solicitud de aprobación a Telegram. Cada DM en la lista blanca recibe un mensaje como 🔐 Permission: Bash con botones See more, ✅ Allow y ❌ Deny. También puedes responder yes <id> o no <id> con el ID de cinco letras del mensaje. Solo los usuarios en la lista blanca pueden responder, y una solicitud solo puede responderse una vez; cada copia del mensaje muestra entonces el resultado. Los miembros del grupo no pueden aprobar.

Para omitir el viaje de ida y vuelta para herramientas que siempre permites, listalas en access.json:

{ "autoApproveTools": ["Read", "Grep", "Glob"] }

El daemon se ejecuta con --dangerously-skip-permissions, por lo que nunca pregunta. Esto es para sesiones que inicias sin esa bandera.

Reacciones de confirmación

El bot puede reaccionar a los mensajes entrantes con un emoji para indicar que los recibió y los está procesando. Esto está controlado por el campo ackReaction en access.json:

{
  "ackReaction": "👀"
}

Flujo de reacciones:

Etapa	Emoji	Cuándo
Recibido	`👀` (configurable vía `ackReaction`)	Inmediatamente al recibir
Procesando voz	`✍`	Al transcribir un mensaje de voz
Trabajando	`🔥`	Durante tareas largas (múltiples llamadas a herramientas, investigación, generación de código)
Listo	`👍`	Después de enviar la respuesta

Telegram solo mantiene una reacción de bot por mensaje, por lo que cada nueva reacción reemplaza la anterior, creando una progresión de estado natural.

Nota: ackReaction no está establecido por defecto. Para habilitarlo, añádelo a tu ~/.claude/channels/telegram/access.json. Solo acepta emojis de la lista blanca de reacciones fija de Telegram. Opciones comunes: 👀, ⚡, 🔥.

Buffer de historial de mensajes

Cada mensaje que fluye a través del bot se captura en una base de datos SQLite local y se persiste entre reinicios. Claude obtiene contexto sin pedir a los usuarios que se repitan.

~/.claude/channels/telegram/data/messages.db

Cómo funciona:

Un middleware de grammY intercepta TODOS los mensajes (incluidos los mensajes de grupo sin mención @bot) antes de la verificación de puerta
Tanto los mensajes entrantes como las respuestas del bot se almacenan con deduplicación INSERT OR REPLACE
Los últimos 5 mensajes se inyectan automáticamente en cada notificación para que Claude siempre tenga contexto continuo
get_history recupera hasta 200 mensajes con paginación; search_messages realiza búsqueda de subcadenas
El modo WAL de SQLite asegura escrituras a prueba de fallos: si Claude Code falla, la base de datos se recupera automáticamente en el próximo inicio
El buffer continuo se poda automáticamente: límite de 500 mensajes/chat, TTL de 14 días, límite duro de 50 MB

Limitaciones

La API de Bot de Telegram no expone ningún endpoint de historial nativo: los bots solo ven mensajes en tiempo real. Resolvemos esto con un almacén de mensajes SQLite local (ver Historial de mensajes abajo). Cada mensaje que fluye a través del bot se captura y persiste, dando a Claude contexto completo entre reinicios a través de las herramientas get_history y search_messages. El historial está disponible desde que el bot se unió al chat.

Las fotos y los mensajes de voz se descargan con avidez al llegar: no hay forma de obtener archivos adjuntos de mensajes históricos a través de la API de Bot.

Hoja de ruta

Completado

Planificado

Mensajes programados -- Enviar mensajes en un momento específico
Soporte multi-bot -- Ejecutar múltiples bots desde una instancia de servidor
Límite de velocidad y estadísticas de uso -- Rastrear uso de tokens y establecer límites por usuario
Modo webhook -- Alternativa al polling para despliegues de producción
Comandos personalizados -- Definir comandos de bot que se asignen a habilidades de Claude Code

Contribuciones

Este es un proyecto comunitario. ¡Queremos tu ayuda!

Haz un fork del repositorio
Crea una rama de características (git checkout -b feature/your-feature)
Haz tus cambios
Prueba con un bot real de Telegram
Abre un PR con una descripción clara de lo que cambiaste y por qué

Directrices

Mantén los cambios enfocados: una característica por PR
Prueba con interacciones reales de Telegram, no solo pruebas unitarias
Actualiza el README si añades nuevas características o herramientas
Sigue el estilo de código existente (TypeScript, biblioteca grammy)

Créditos

Plugin original de Anthropic (fuente) -- licencia Apache 2.0
Supercharged por @k1p1l0 y colaboradores
Inspirado en el lanzamiento de Claude Code Channels por @boris_cherny

Licencia

Apache 2.0 -- Igual que el original. Ver LICENSE.