Claude Code ↔ Telegram Bridge

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

Esto 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 luchan por el mismo token de Telegram.

Parche de seguridad

El plugin original tiene un problema de divulgación: los comandos /start, /help y /status se registran antes de que se ejecute la puerta de acceso. Bajo 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 incluidos en la lista blanca se descartan silenciosamente. En modo 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. Instalar el servidor

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

2. Configurar 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. Instalar 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. Instalar el lanzador

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

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

5. Bloquear el acceso (recomendado)

Por defecto, el bot está en modo 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

Iniciar 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 por 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. Gratis para uso personal.

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

• tmux — multiplexor de terminal. La sesión sobrevive a las desconexiones de 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á activo en Telegram. Cierras Termius, la sesión de tmux persiste, el bot sigue funcionando. 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 sondeo 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 estado de sondeo 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 sondeo 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 sondean el 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 oficial del canal de Telegram de Claude Code).

Contacto

• GitHub: Swigler