Claude Code ↔ Telegram Bridge

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

Dies ist ein Fork des offiziellen Claude-Code-Telegram-Kanal-Plugins mit einem Sicherheitspatch 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-Design: Nur eine Claude-Sitzung kann den Bot gleichzeitig besitzen. tgpin erwirbt eine Lock-Datei, 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.

Sicherheitspatch

Das Upstream-Plugin hat ein Offenlegungsproblem: /start, /help und /status-Befehle 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-Bridge handelt – was preisgibt, dass der Bot existiert und was er tut.

Der Patch fügt einen commandMuted()-Schutz hinzu: Im Allowlist- oder Disabled-Modus werden Befehle von Benutzern außerhalb der Allowlist stillschweigend verworfen. Im Pairing-Modus funktionieren sie normal (da /start der Weg ist, wie 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. Eine Aktivierung würde den Bot unsterblich machen und mit dem Pin-Design in Konflikt geraten.

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 befindet sich 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 auf Telegram eine Nachricht an @userinfobot 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 vom Smartphone aus zu betreiben. Der Stack:

• Tailscale – Mesh-VPN. Dein Smartphone und dein Rechner sehen sich in einem privaten Netzwerk, kein Port-Forwarding, keine öffentliche IP nötig. Kostenlos für den privaten Gebrauch.

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

• tmux – Terminal-Multiplexer. Die Sitzung überlebt SSH-Verbindungsabbrü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 aktiv, solange die tmux-Sitzung existiert. SSH-Abbrüche töten ihn nicht. Schließe die tmux-Sitzung und der Bot stirbt – das ist Absicht.

Der Workflow: Du bist im Bus, öffnest Termius auf deinem Smartphone, verbindest dich per SSH über Tailscale mit deinem Rechner, hängst dich an die tmux-Sitzung an – 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 einsteigen.

Umgang mit Berechtigungen

Tool-Aufrufe erscheinen als Genehmigen/Ablehnen-Buttons in Telegram. Die Sitzung läuft im --permission-mode default, daher erfordern destruktive Operationen (Datei-Schreibvorgänge, Shell-Befehle) vor der Ausführung deine explizite Bestätigung.

Architekturentscheidungen

Warum sitzungsgebunden?

Ein immer aktiver Bot bedeutet eine immer aktive Claude-Sitzung, die Ressourcen verbraucht und möglicherweise auf der Grundlage eines veralteten Kontexts handelt. Das Pin-Design bedeutet, dass der Bot aktiv ist, wenn du ihn willst, und inaktiv, 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 erzeugt. Die Trennung bedeutet:

• Der Server kann unabhängig von Claude neu starten

• Der Proxy kann sich wieder mit einem laufenden Server verbinden

• Kein Polling-Zustand geht bei einem Neustart einer Claude-Sitzung 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 über die Maschine selbst hinaus.

Ein Poller pro Token

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

Dateien

Lizenz

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

Kontakt

• GitHub: Swigler