Claude Code Telegram Kit

Keine weitere Telegram-Brücke. Anthropic's offizieller Claude Code Channel kümmert sich um eingehende Nachrichten. Dieses Kit behebt die beiden Dinge, die es nicht tut: Markdown, das Telegram's Parser übersteht, und das Zurücksetzen des Kontexts von Ihrem Telefon.

Forschungsvorschau-Infrastruktur. Überprüfen Sie das Sicherheitsmodell, bevor Sie es an einen Rechner mit wertvollen Daten anschließen.

Das gleiche Markdown-Dokument, beide Pfade. Das offizielle reply-Tool verwendet standardmäßig format: "text", daher kommt das Markup wörtlich an; sein markdownv2-Modus verlagert die MarkdownV2-Escaping auf das Modell, wo ein einzelner fehlender Zeichen den Sendevorgang scheitern lässt. send_reply nimmt das Dokument unescaped und wählt selbst den Transport. (Die Abbildungen werden von beiden Pfaden gerendert, nicht von Geräte-Screenshots.)

Warum es dieses Kit gibt

Jedes andere „Claude Code + Telegram“-Projekt ersetzt den offiziellen Kanal: einen eigenen Poller, eigenes Session-Management, eigenes Pairing. Dieses hier tut das nicht. Eingehendes Polling, Sender-Pairing, Anhänge und Berechtigungsweitergabe bleiben bei Anthropic's Plugin. Das Kit fügt zwei begrenzte Outbound-/Control-Fähigkeiten daneben hinzu, ohne einen zweiten getUpdates-Consumer:

• Telegram Renderer MCP — ein kanonisches send_reply(raw Markdown)-Tool mit deterministischem Rich Message vs. MarkdownV2-Routing und Fallback nur bei dauerhaftem Fehler.

• Session Control MCP — ein genehmigungspflichtiger /reset-Pfad, unterstützt von einem root-eigenen, fail-closed lokalen Reset-Helfer, der von PID 1 ausgeführt wird.

Beide Lücken sind upstream offen. Dieses Kit ist die vorläufige Antwort:

• anthropics/claude-code#39684 — keine Möglichkeit, den Kontext remote zu löschen oder zurückzusetzen

• anthropics/claude-code#36622 und claude-plugins-official#774 — Anfrage für einen MarkdownV2 parse_mode

Schnellstart

Erfordert das offizielle telegram@claude-plugins-official-Plugin, das bereits gekoppelt und funktionsfähig ist.

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)"

Kopieren Sie dann examples/.mcp.json, examples/telegram-settings.json und examples/CLAUDE.md in Ihr Claude-Projekt und ersetzen Sie USER durch Ihre eigenen Pfade. Senden Sie eine Nachricht mit einer GFM-Tabelle; der Renderer sollte mode: rich melden.

Der Renderer funktioniert eigenständig. /reset benötigt zusätzlich den Root-Helfer, der separat durch die exakte Commit-Prozedur in der session-control README installiert wird.

Für Produktionsbereitstellung, Rollback und Verifizierung folgen Sie dem Operations-Runbook anstelle dieses Abschnitts.

Architektur

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

Der Renderer und die Control-MCPs verwenden den Token des offiziellen Kanals und die access.json-Autorität wieder. Sie erfordern dmPolicy: allowlist, sichere 0600-Zustandsdateien und exakte Zielmitgliedschaft.

Design-Invarianten

Diese fünf definieren den Schadensradius:

• Ein Telegram-getUpdates-Consumer pro Bot-Token.

• Kein willkürliches Bot-API-Methoden-Tool.

• Kein willkürliches Shell-Befehl-Tool.

• Timeouts, 429er, 5xx-Antworten und unbekannte Ergebnisse lösen nie einen erneuten Sendevorgang aus.

• PID 1 besitzt die Reset-Ausführung, bevor der Claude-Prozess beendet wird.

Der vollständige Satz befindet sich in docs/design-invariants.md.

Repository-Struktur

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

Voraussetzungen

• Linux mit systemd und procfs, eingehängt unter /proc

• Claude Code 2.1.234 oder neuer

• Bun 1.3.14 oder neuer

• Python 3.11 oder neuer

• Anthropic's offizielles telegram@claude-plugins-official-Plugin

Installationsmodell

Führen Sie die Produktion nicht aus einem veränderbaren Entwicklungs-Checkout aus. Installieren Sie einen exakten Commit in ein versioniertes Release-Verzeichnis:

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

scripts/deploy_local.py extrahiert ein Git-Archiv mit einem Python 3.11-kompatiblen No-Link/No-Traversal-Extraktor, installiert Produktionsabhängigkeiten, überprüft den Release-Beleg und tauscht atomar current/previous aus. Es installiert niemals root-eigene Dateien.

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

Bewahren Sie Telegram-Anmeldeinformationen und Zulassungslisten im Zustandsverzeichnis von Claude auf und halten Sie die Reset-Konfiguration root-eigen unter /etc/claude-code-telegram-kit/.

Session-Reset

Die lokale Wiederherstellungsinstanz ist:

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

Der optionale Telegram-/reset-Befehl ist ein dünnes MCP-Frontend. Er kann keinen Claude-Prozess wiederherstellen, der bereits keine Nachrichten mehr empfangen kann; halten Sie den lokalen Helfer als Notfallpfad bereit.

Entwicklung

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

Sicherheit

Lesen Sie SECURITY.md vor der Bereitstellung. Committen Sie niemals Bot-Tokens, Chat-IDs, Transkripte, dienstspezifische Pfade oder Live-Reset-Konfiguration.

Projektstatus

Der Code wird aus einer live, verifizierten Bereitstellung extrahiert und dann in ein öffentliches Clean-Room-Repository verallgemeinert. APIs können sich vor 1.0.0 ändern.

Die erste Veröffentlichung ist nur als Quellcode. Workspace-Pakete sind als private markiert und werden nicht auf npm veröffentlicht; installieren Sie von einem exakten Git-Commit mit dem versionierten Bereitstellungsskript.

Lizenz

Apache-2.0. Siehe LICENSE, NOTICE und THIRD_PARTY_NOTICES.md. Release-Verfahren: RELEASING.md.

Dieses Projekt ist unabhängig und wird weder von Anthropic noch von Telegram unterstützt.