Claude Code Telegram Kit

No es otro puente de Telegram. El Claude Code Channel oficial de Anthropic gestiona la recepción de mensajes entrantes. 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. Revise el modelo de seguridad antes de conectarlo a una máquina con datos valiosos.

El mismo documento Markdown, ambas rutas. La herramienta oficial reply por defecto usa 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 provoca que falle el envío. send_reply toma el documento sin escapar y elige el transporte por sí misma. (Las figuras se generan desde ambas rutas, no son capturas de pantalla del dispositivo.)

Por qué existe esto

Cualquier otro proyecto "Claude Code + Telegram" sustituye al Canal oficial: su propio sondeo, su propia gestión de sesiones, su propio emparejamiento. Este no. El sondeo entrante, el emparejamiento del remitente, los archivos adjuntos y el relé de permisos quedan en manos del plugin de Anthropic. El kit añade dos capacidades limitadas de salida/control a su lado, sin un segundo consumidor de getUpdates:

• Telegram Renderer MCP — una herramienta canónica send_reply(raw Markdown) con enrutamiento determinista entre Rich Message y MarkdownV2, y respaldo solo en caso de fallo permanente.

• Session Control MCP — una ruta /reset con control de aprobación respaldada por un asistente de reinicio local de propiedad raíz y fail-closed, que ejecuta PID 1.

Ambas carencias están abiertas río arriba. 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

Inicio rápido

Requiere el plugin oficial telegram@claude-plugins-official ya 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 a tu proyecto de Claude, reemplazando USER con tus propias rutas. Envía un mensaje con una tabla GFM; el renderizador debería informar mode: rich.

El renderizador funciona por sí solo. /reset necesita además el asistente raíz, 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 runbook 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

El renderizador y los MCP de control reutilizan el token y la autoridad de access.json del Canal oficial. Requieren dmPolicy: allowlist, archivos de estado seguros con 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 de método arbitrario de la API de Bot.

• Ninguna herramienta de comando shell arbitrario.

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

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

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

Distribución 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 superior

• Bun 1.3.14 o superior

• Python 3.11 o superior

• 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 etiquetado:

~/.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 recorrido, instala dependencias de producción, verifica el recibo de la versión y cambia atómicamente current/previous. Nunca instala archivos de propiedad raíz.

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 reinicio de propiedad raíz bajo /etc/claude-code-telegram-kit/.

Reinicio 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 una interfaz MCP ligera. No puede recuperar un proceso de Claude que ya no pueda recibir mensajes; mantén el asistente 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 reinicio en vivo.

Estado del proyecto

El código se ha extraído de un despliegue activo y verificado, y luego se ha generalizado en un repositorio público aislado. Las API pueden cambiar antes de 1.0.0.

La versión inicial es solo fuente. Los paquetes del workspace 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.