Claude Code ↔ Telegram Bridge

Eine sitzungsgebundene Telegram-Brücke für Claude Code. Der Bot lebt genau so lange wie deine Terminal-Sitzung – starte ihn, nutze ihn, schließe ihn. Kein Dauer-Daemon.

Dies ist ein Fork des offiziellen Claude Code Telegram-Kanal-Plugins mit einem Sicherheits-Patch und einem portablen Deployment-Setup mit tmux + Tailscale.

So funktioniert es

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
└─────────────────────┘

Das Pin-Konzept: Nur eine Claude-Sitzung kann den Bot gleichzeitig besitzen. tgpin erwirbt eine Sperrdatei, startet den Poller und gibt beides frei, wenn die Sitzung endet. Dies verhindert den 409-Konflikt, der auftritt, wenn zwei Poller um dasselbe Telegram-Token kämpfen.

Related MCP server: tsgram-mcp

Sicherheits-Patch

Das Upstream-Plugin hat ein Offenlegungsproblem: Die Befehle /start, /help und /status werden registriert, bevor die Zugriffskontrolle greift. Unter dmPolicy: "allowlist" erhält ein Fremder, der den Bot findet, eine hilfreiche Antwort, die erklärt, dass es sich um eine Claude-Code-Brücke handelt – was preisgibt, dass der Bot existiert und was er tut.

Der Patch fügt eine commandMuted()-Absicherung hinzu: Im Allowlist- oder deaktivierten Modus werden Befehle von nicht in der Allowlist stehenden Benutzern stillschweigend verworfen. Im Pairing-Modus funktionieren sie normal (da /start der Weg ist, über den neue Benutzer das Pairing lernen).

Das sind +15 Zeilen, keine Löschungen, sichtbar im Git-Diff.

Einrichtung

Voraussetzungen

• Claude Code CLI installiert

• Bun Runtime

• Ein Telegram-Bot-Token von @BotFather

1. Server installieren

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

2. Bot-Token konfigurieren

mkdir -p ~/.claude/channels/telegram
echo "TELEGRAM_BOT_TOKEN=YOUR_TOKEN_HERE" > ~/.claude/channels/telegram/.env
chmod 600 ~/.claude/channels/telegram/.env

3. systemd-User-Unit installieren

mkdir -p ~/.config/systemd/user
cp telegram-mcp.service ~/.config/systemd/user/
systemctl --user daemon-reload

Aktiviere den Dienst nicht – tgpin startet und stoppt ihn automatisch. Wenn du ihn aktivierst, würde der Bot unsterblich und mit dem Pin-Konzept kollidieren.

4. Launcher installieren

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

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

5. Zugriff sperren (empfohlen)

Standardmäßig ist der Bot im Pairing-Modus – jeder, der ihm eine Direktnachricht schickt, erhält einen Pairing-Code. Um ihn auf deine Telegram-Benutzer-ID zu beschränken:

cat > ~/.claude/channels/telegram/access.json << 'EOF'
{
  "dmPolicy": "allowlist",
  "allowFrom": ["YOUR_TELEGRAM_USER_ID"],
  "groups": {},
  "pending": {}
}
EOF

Finde deine Benutzer-ID, indem du eine Nachricht an @userinfobot auf Telegram sendest.

Verwendung

Eine Sitzung starten

tg              # start Claude with Telegram bridge
tg --continue   # resume the last conversation

Portabler Zugriff (tmux + Tailscale + Termius)

Die eigentliche Stärke liegt darin, dies per SSH von deinem Telefon aus zu betreiben. Der Stack:

• Tailscale – Mesh-VPN. Dein Telefon und dein Rechner sehen sich in einem privaten Netzwerk, kein Port-Forwarding, keine öffentliche IP nötig. Persönlicher Plan inklusive.

• Termius – SSH-Client für Android/iOS. Unterstützt Schlüssel-Authentifizierung, persistente Sitzungen und Tailscale-Adressen. Der Starter-Plan reicht aus.

• tmux – Terminal-Multiplexer. Die Sitzung überlebt SSH-Abbrüche.

# 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

Der Bot bleibt so lange aktiv, wie die tmux-Sitzung existiert. SSH-Abbrüche töten ihn nicht. Schließe die tmux-Sitzung und der Bot stirbt – gewollt.

Der Workflow: Du bist im Bus, öffnest Termius auf deinem Telefon, verbindest dich per SSH über Tailscale mit deinem Rechner, hängst dich an die tmux-Sitzung – Claude ist live auf Telegram. Schließe Termius, die tmux-Sitzung bleibt bestehen, der Bot läuft weiter. Du kannst später von überall wieder darauf zugreifen.

Berechtigungsverwaltung

Tool-Aufrufe erscheinen als Genehmigen/Ablehnen-Schaltflächen in Telegram. Die Sitzung läuft im Modus --permission-mode default, daher erfordern destruktive Operationen (Dateischreibvorgänge, Shell-Befehle) deine ausdrückliche Bestätigung, bevor sie ausgeführt werden.

Architekturentscheidungen

Warum sitzungsgebunden?

Ein immer aktiver Bot bedeutet eine immer aktive Claude-Sitzung, die Ressourcen verbraucht und möglicherweise mit veraltetem Kontext arbeitet. Das Pin-Konzept bedeutet, dass der Bot aktiv ist, wenn du ihn willst, und tot, wenn nicht. Das ist ein Feature, keine Einschränkung.

Warum zwei Dateien (server.ts + proxy.ts)?

Der Server läuft als systemd-Unit und hält die Telegram-Polling-Verbindung. Der Proxy wird von Claude als Stdio-MCP-Transport gestartet. Die Trennung bedeutet:

• Der Server kann unabhängig von Claude neu gestartet werden

• Der Proxy kann sich mit einem laufenden Server neu verbinden

• Beim Neustart einer Claude-Sitzung geht kein Polling-Status verloren

Warum kein Webhook?

Webhooks benötigen eine öffentliche URL, TLS und Port-Forwarding. Long Polling funktioniert überall – hinter NAT, auf einem Laptop, auf einem VPS. Keine Infrastruktur außer der Maschine selbst.

Ein Poller pro Token

Die Bot-API von Telegram gibt 409 Conflict zurück, wenn zwei Prozesse dasselbe Token abfragen. Die Sperrdatei (pinned.lock) erzwingt genau einen Poller. Wenn eine Sitzung ohne Bereinigung abstürzt, erkennt das nächste tgpin die veraltete PID und beansprucht die Sperre zurück.

Dateien

Lizenz

Apache-2.0 (wie beim Upstream-Claude-Code-Telegram-Plugin).

Kontakt

• GitHub: Swigler