Claude Code Telegram-Kit

Keine weitere Telegram-Brücke. Anthropics offizieller Claude Code Channel behält eingehende Nachrichten. Dieses Kit behebt zwei Dinge, die er nicht kann: Markdown, das Telegram-Parser übersteht, und das Zurücksetzen des Kontexts vom Telefon aus.

Research-Preview-Infrastruktur. Überprüfen Sie das Sicherheitsmodell, bevor Sie es mit einem Rechner mit wertvollen Daten verbinden.

Das selbe Markdown-Dokument, beide Pfade. Das offizielle reply-Werkzeug verwendet standardmäßig format: "text", daher kommt Markup wörtlich an; sein markdownv2-Modus schiebt die MarkdownV2-Escape-Behandlung auf das Modell, wo ein einzelner fehlender Zeichen den Sendevorgang zum Scheitern bringt. send_reply nimmt das Dokument unescaped entgegen und wählt selbst das Transportmittel. (Abbildungen werden von beiden Pfaden gerendert, keine Geräte-Screenshots.)

Warum es dies gibt

Jedes andere „Claude Code + Telegram“-Projekt ersetzt den offiziellen Channel: eigener Poller, eigenes Sitzungsmanagement, eigenes Pairing. Dieses nicht. Eingehendes Pollen, Senderzuordnung, Anhänge und Berechtigungsweitergabe bleiben beim Anthropic-Plugin. Das Kit fügt daneben zwei begrenzte ausgehende/Steuerungsfähigkeiten hinzu, ohne einen zweiten getUpdates-Konsumenten:

• Telegram Renderer MCP — ein einziges kanonisches send_reply(rohes Markdown)-Werkzeug mit deterministischem Rich Message vs. MarkdownV2-Routing, permanent-only-Fallback und 👀 → 👍/👎-Verarbeitungsreaktionen.

• Session Control MCP — ein genehmigungsgesteuerter /reset-Pfad, der die bestätigte Akzeptanzreaktion abschließt und dann die Ausführung an einen root-eigenen, fail-closed lokalen Reset-Helfer übergibt, den PID 1 ausführt.

Beide Lücken sind upstream offen. Dieses Kit ist die Übergangslösung:

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

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

Related MCP server: tsgram-mcp

Schnellstart

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

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. Führen Sie examples/access-ux.json in die access.json des offiziellen Channels zusammen, um die anfängliche 👀-Bestätigung zu aktivieren. Senden Sie eine Nachricht mit einer GFM-Tabelle; der Renderer sollte mode: rich melden und 👀 durch 👍 ersetzen.

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

Für Produktionsbereitstellung, Rollback und Verifizierung folgen Sie dem Operations-Runbook anstatt diesem Abschnitt.

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

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

Entwurfsinvarianten

Diese fünf definieren den Schadensbereich:

• Ein Telegram getUpdates-Konsument pro Bot-Token.

• Kein willkürliches Bot-API-Methodenwerkzeug.

• Kein willkürliches Shell-Befehlswerkzeug.

• Zeitüberschreitungen, 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.

Die vollständige Liste 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

Anforderungen

• Linux mit systemd und procfs gemountet unter /proc

• Claude Code 2.1.234 oder neuer

• Bun 1.3.14 oder neuer

• Python 3.11 oder neuer

• Anthropics offizielles telegram@claude-plugins-official-Plugin

Installationsmodell

Produktion nicht aus einem veränderbaren Entwicklungs-Checkout ausführen. 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, verifiziert den Release-Empfang 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-Zugangsdaten und Zulässigkeitslisten unter Claudes Zustandsverzeichnis auf, und bewahren Sie die Reset-Konfiguration root-eigen unter /etc/claude-code-telegram-kit/ auf.

Sitzungsreset

Die lokale Wiederherstellungsautorität ist:

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

Der optionale Telegram /reset-Befehl ist eine dünne MCP-Frontend. Er kann keinen Claude-Prozess wiederherstellen, der bereits keine Nachrichten mehr empfangen kann; halten Sie den lokalen Helfer als Break-Glass-Pfad 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 laufenden, verifizierten Bereitstellung extrahiert und dann in ein öffentliches Repository im Reinraum verallgemeinert. APIs können sich vor 1.0.0 ändern.

Die Erstveröffentlichung erfolgt 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.