Claude Code ↔ Puente de Telegram

Un puente de Telegram anclado a la sesión para Claude Code. El bot vive exactamente mientras dura tu sesión de terminal: inícialo, úsalo, ciérralo. Sin demonio siempre activo.

Este es un fork del plugin oficial del canal de Telegram de Claude Code con un parche de seguridad y una configuración de despliegue portátil usando tmux + Tailscale.

Cómo Funciona

Phone (Telegram)
  │
  ▼
┌─────────────────────┐
│  server.ts           │  Standalone MCP HTTP server
│  Polls Telegram      │  Runs as a systemd user unit
│  Queues messages     │  Starts/stops with the pin
└──────────┬──────────┘
           │ SSE (/events)
           ▼
┌─────────────────────┐
│  proxy.ts            │  Stdio MCP proxy
│  Bridges to Claude   │  Spawned by Claude Code
│  Owns the pin lock   │  One session at a time
└──────────┬──────────┘
           │ stdio
           ▼
┌─────────────────────┐
│  Claude Code         │  Your session
│  Reads messages      │  Calls reply/react/edit
│  Full tool access    │  Permission buttons in TG
└─────────────────────┘

El diseño de anclaje: Solo una sesión de Claude puede ser dueña del bot a la vez. tgpin adquiere un archivo de bloqueo, inicia el poller y libera ambos cuando la sesión termina. Esto evita el conflicto 409 que ocurre cuando dos pollers pelean por el mismo token de Telegram.

Related MCP server: tsgram-mcp

Parche de Seguridad

El plugin upstream tiene un problema de divulgación: los comandos /start, /help y /status se registran antes de que se ejecute la puerta de acceso. Con dmPolicy: "allowlist", un extraño que encuentre el bot recibe una respuesta útil explicando que es un puente de Claude Code, filtrando que el bot existe y qué hace.

El parche añade una protección commandMuted(): en modo allowlist o deshabilitado, los comandos de usuarios no permitidos se descartan silenciosamente. En modo de emparejamiento, funcionan normalmente (ya que /start es como los nuevos usuarios aprenden a emparejarse).

Esto son +15 líneas, sin eliminaciones, visible en el diff de git.

Configuración

Requisitos previos

• CLI de Claude Code instalado

• Runtime de Bun

• Un token de bot de Telegram de @BotFather

1. Instala el servidor

mkdir -p ~/.claude/telegram-server
cp server.ts proxy.ts package.json ~/.claude/telegram-server/
cd ~/.claude/telegram-server && bun install

2. Configura el token del bot

mkdir -p ~/.claude/channels/telegram
echo "TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE" > ~/.claude/channels/telegram/.env
chmod 600 ~/.claude/channels/telegram/.env

3. Instala la unidad de usuario de systemd

mkdir -p ~/.config/systemd/user
cp telegram-mcp.service ~/.config/systemd/user/
systemctl --user daemon-reload

No habilites el servicio — tgpin lo inicia y lo detiene automáticamente. Habilitarlo haría que el bot fuera inmortal y lucharía contra el diseño de anclaje.

4. Instala el lanzador

cp tgpin ~/bin/tgpin
chmod +x ~/bin/tgpin

# Optional: alias in your .bashrc
echo 'alias tg="~/bin/tgpin"' >> ~/.bashrc

5. Bloquea el acceso (recomendado)

Por defecto, el bot está en modo de emparejamiento: cualquiera que le envíe un mensaje directo recibe un código de emparejamiento. Para bloquearlo a tu ID de usuario de Telegram:

cat > ~/.claude/channels/telegram/access.json << 'EOF'
{
  "dmPolicy": "allowlist",
  "allowFrom": ["YOUR_TELEGRAM_USER_ID"],
  "groups": {},
  "pending": {}
}
EOF

Encuentra tu ID de usuario enviando un mensaje a @userinfobot en Telegram.

Uso

Inicia una sesión

tg              # start Claude with Telegram bridge
tg --continue   # resume the last conversation

Acceso portátil (tmux + Tailscale + Termius)

El verdadero poder es ejecutar esto a través de SSH desde tu teléfono. La pila:

• Tailscale — VPN de malla. Tu teléfono y tu máquina se ven entre sí en una red privada, sin reenvío de puertos, sin IP pública necesaria. Plan personal incluido.

• Termius — Cliente SSH para Android/iOS. Soporta autenticación por clave, sesiones persistentes y direcciones Tailscale. El plan inicial es suficiente.

• tmux — multiplexor de terminal. La sesión sobrevive a las desconexiones SSH.

# On your machine (once):
tmux new -s claude
tg

# Detach: Ctrl+B, then D

# From your phone (Termius → Tailscale IP):
ssh your-machine
tmux attach -t claude

El bot permanece activo mientras exista la sesión de tmux. Las caídas de SSH no lo matan. Cierra la sesión de tmux y el bot muere, por diseño.

El flujo de trabajo: Estás en el autobús, abres Termius en tu teléfono, te conectas por SSH a tu máquina a través de Tailscale, te adjuntas a la sesión de tmux — Claude está en vivo en Telegram. Cierras Termius, la sesión de tmux persiste, el bot sigue corriendo. Lo retomas más tarde desde cualquier lugar.

Manejo de permisos

Las llamadas a herramientas aparecen como botones de aprobar/rechazar en Telegram. La sesión se ejecuta en --permission-mode default, por lo que las operaciones destructivas (escrituras de archivos, comandos de shell) requieren tu toque explícito antes de ejecutarse.

Decisiones de Arquitectura

¿Por qué anclado a la sesión?

Un bot siempre activo significa una sesión de Claude siempre activa consumiendo recursos y potencialmente actuando sobre contexto obsoleto. El diseño de anclaje significa que el bot está vivo cuando lo quieres, muerto cuando no. Esto es una característica, no una limitación.

¿Por qué dos archivos (server.ts + proxy.ts)?

El servidor se ejecuta como una unidad de systemd y mantiene la conexión de polling de Telegram. El proxy es generado por Claude como transporte MCP stdio. Separarlos significa:

• El servidor puede reiniciarse independientemente de Claude

• El proxy puede reconectarse a un servidor en ejecución

• No se pierde el estado de polling durante un reinicio de la sesión de Claude

¿Por qué no un webhook?

Los webhooks necesitan una URL pública, TLS y reenvío de puertos. El polling largo funciona en cualquier lugar — detrás de NAT, en un portátil, en un VPS. Cero infraestructura más allá de la propia máquina.

Un poller por token

La API de Bot de Telegram devuelve 409 Conflict si dos procesos hacen polling del mismo token. El archivo de bloqueo (pinned.lock) garantiza exactamente un poller. Si una sesión se bloquea sin limpieza, el siguiente tgpin detecta el PID obsoleto y recupera el bloqueo.

Archivos

Licencia

Apache-2.0 (igual que el plugin upstream de Claude Code para Telegram).

Contacto

• GitHub: Swigler