Claude Code Telegram Kit

No es otro puente de Telegram. El canal oficial de Claude Code de Anthropic mantiene la entrada. Este kit soluciona las dos cosas que no hace: Markdown que sobrevive al analizador de Telegram y restablecer el contexto desde tu teléfono.

Infraestructura en vista previa de investigación. Revisa el modelo de seguridad antes de conectarlo a una máquina con datos valiosos.

El mismo documento Markdown, ambas rutas. La herramienta oficial reply usa por defecto format: "text", por lo que el marcado llega literal; su modo markdownv2 traslada el escape de MarkdownV2 al modelo, donde un solo carácter omitido hace fallar el envío. send_reply toma el documento sin escapar y elige el transporte por sí mismo. (Las figuras se renderizan desde ambas rutas, no son capturas de pantalla del dispositivo.)

Por qué existe esto

Cualquier otro proyecto "Claude Code + Telegram" reemplaza el canal oficial: su propio poller, su propia gestión de sesiones, su propio emparejamiento. Este no lo hace. El polling de entrada, el emparejamiento del remitente, los archivos adjuntos y el reenvío de permisos permanecen en el plugin de Anthropic. El kit añade dos capacidades de salida/control acotadas a su lado, sin un segundo consumidor de getUpdates:

• Telegram Renderer MCP — una herramienta canónica send_reply(raw Markdown) con enrutamiento determinista entre mensaje enriquecido y MarkdownV2, fallback solo permanente y reacciones de procesamiento 👀 → 👍/👎.

• Session Control MCP — una ruta /reset con aprobación que finaliza la reacción de aceptación confirmada y luego entrega la ejecución a un ayudante de restablecimiento local propiedad de root, de cierre seguro en caso de fallo, que ejecuta PID 1.

Ambas carencias están abiertas en los repositorios oficiales. Este kit es la respuesta provisional:

• anthropics/claude-code#39684 — no hay forma de limpiar o restablecer el contexto de forma remota

• anthropics/claude-code#36622 y claude-plugins-official#774 — solicitud de un parse_mode MarkdownV2

Related MCP server: tsgram-mcp

Inicio rápido

Requiere que el plugin oficial telegram@claude-plugins-official ya esté emparejado y funcionando.

git clone https://github.com/project-tharsis/claude-code-telegram-kit
cd claude-code-telegram-kit
bun install --frozen-lockfile
bun run check

sha=$(git rev-parse HEAD)
python3 scripts/deploy_local.py install --repo . --ref "$sha" --bun "$(command -v bun)"

Luego copia examples/.mcp.json, examples/telegram-settings.json y examples/CLAUDE.md en tu proyecto de Claude, reemplazando USER con tus propias rutas. Fusiona examples/access-ux.json en el access.json del canal oficial para habilitar el acuse de recibo inicial 👀. Envía un mensaje con una tabla GFM; el renderizador debería informar mode: rich y reemplazar 👀 con 👍.

El renderizador funciona por sí solo. /reset necesita además el ayudante root, instalado por separado mediante el procedimiento de commit exacto en el README de session-control.

Para despliegue en producción, reversión y verificación, sigue el manual de operaciones en lugar de esta sección.

Arquitectura

Telegram
  -> telegram@claude-plugins-official     # sole inbound poller
  -> Claude Code
     -> telegram-renderer MCP              # bounded outbound rendering
     -> session-control MCP                # bounded reset scheduling
        -> systemd transient unit
        -> root-owned session reset helper

Los MCPs de renderizado y control reutilizan el token del canal oficial y la autoridad de access.json. Requieren dmPolicy: allowlist, archivos de estado seguros 0600 y pertenencia exacta al destino.

Invariantes de diseño

Estos cinco definen el radio de explosión:

• Un solo consumidor de getUpdates de Telegram por token de bot.

• Ninguna herramienta arbitraria del método de la API de Bot.

• Ninguna herramienta arbitraria de shell.

• Los tiempos de espera, los 429, las respuestas 5xx y los resultados desconocidos nunca desencadenan un reenvío.

• PID 1 posee la ejecución del restablecimiento antes de que se termine el proceso de Claude.

El conjunto completo está en docs/design-invariants.md.

Estructura del repositorio

packages/
  shared/                  Telegram authority validation
  telegram-renderer-mcp/   Markdown renderer and MCP server
  session-control-mcp/     Reset controller, MCP server, root helper
examples/                  Generic Claude, MCP, systemd, and reset config
scripts/                   Versioned local install and rollback

Requisitos

• Linux con systemd y procfs montado en /proc

• Claude Code 2.1.234 o más reciente

• Bun 1.3.14 o más reciente

• Python 3.11 o más reciente

• Plugin oficial telegram@claude-plugins-official de Anthropic

Modelo de instalación

No ejecutes producción desde un checkout de desarrollo mutable. Instala un commit exacto en un directorio de versión con control de versiones:

~/.local/share/claude-code-telegram-kit/
  releases/<git-sha>/
  current -> releases/<git-sha>
  previous -> releases/<previous-sha>

scripts/deploy_local.py extrae un archivo Git con un extractor compatible con Python 3.11 sin enlaces ni recorridos, instala las dependencias de producción, verifica el recibo de la versión y cambia atómicamente current/previous. Nunca instala archivos propiedad de root.

python3 scripts/deploy_local.py status
python3 scripts/deploy_local.py rollback

Mantén las credenciales de Telegram y las listas de permitidos bajo el directorio de estado de Claude, y la configuración de restablecimiento propiedad de root bajo /etc/claude-code-telegram-kit/.

Restablecimiento de sesión

La autoridad de recuperación local es:

sudo claude-code-session-reset --config /etc/claude-code-telegram-kit/reset.json

El comando opcional /reset de Telegram es un frontend MCP ligero. No puede recuperar un proceso de Claude que ya no pueda recibir mensajes; mantén el ayudante local disponible como ruta de emergencia.

Desarrollo

bun install --frozen-lockfile
bun run check
bun audit

Seguridad

Lee SECURITY.md antes del despliegue. Nunca confirmes tokens de bot, IDs de chat, transcripciones, rutas específicas del servicio ni configuración de restablecimiento en vivo.

Estado del proyecto

El código se extrae de un despliegue en vivo y verificado, y luego se generaliza en un repositorio público de sala limpia. Las API pueden cambiar antes de 1.0.0.

La versión inicial es solo código fuente. Los paquetes del espacio de trabajo están marcados como private y no se publican en npm; instala desde un commit exacto de Git con el script de despliegue versionado.

Licencia

Apache-2.0. Consulta LICENSE, NOTICE y THIRD_PARTY_NOTICES.md. Procedimiento de publicación: RELEASING.md.

Este proyecto es independiente y no cuenta con el respaldo de Anthropic ni de Telegram.