Claude Code ↔ Telegram Bridge

Claude Code用のセッションピン型Telegramブリッジです。ボットはターミナルセッションと同じだけ生き続けます——起動して、使って、閉じる。常駐デーモンは不要です。

これは公式のClaude Code Telegramチャンネルプラグインのフォークで、セキュリティパッチと、tmux + Tailscaleを使ったポータブルなデプロイ構成を備えています。

仕組み

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

ピン設計: 同時に1つのClaudeセッションだけがボットを所有できます。tgpinはロックファイルを取得し、ポーラーを起動し、セッション終了時に両方を解放します。これにより、2つのポーラーが同じTelegramトークンをめぐって競合したときに発生する409 Conflictを防ぎます。

セキュリティパッチ

上流プラグインには情報開示の問題があります:/start、/help、/statusコマンドがアクセスゲートの実行前に登録されます。dmPolicy: "allowlist"の下では、ボットを見つけた見知らぬ人が、Claude Codeブリッジであることを説明する親切な応答を受け取ります——ボットが存在し、何をするのかが漏洩します。

パッチはcommandMuted()ガードを追加します:allowlistまたはdisabledモードでは、allowlistに登録されていないユーザーからのコマンドは静かに破棄されます。ペアリングモードでは、通常どおり動作します(/startが新しいユーザーがペアリング方法を学ぶ手段だからです)。

これは+15行、削除なし、git diffで確認できます。

セットアップ

前提条件

• Claude Code CLIがインストールされていること

• Bunランタイム

• @BotFatherから取得したTelegramボットトークン

1. サーバーをインストール

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

2. ボットトークンを設定

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

3. systemdユーザーユニットをインストール

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

サービスは有効化しないでください — tgpinが自動的に開始・停止します。有効化するとボットが不死身になり、ピン設計と競合します。

4. ランチャーをインストール

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

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

5. アクセスをロック(推奨)

デフォルトでは、ボットはペアリングモードです——DMを送ってきた誰にでもペアリングコードが渡されます。自分のTelegramユーザーIDにロックするには:

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

ユーザーIDは、Telegramで@userinfobotにメッセージを送信すると確認できます。

使い方

セッションを開始

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

ポータブルアクセス(tmux + Tailscale + Termius)

本当の力は、スマホからSSHでこれを実行することにあります。スタックは以下のとおり:

• Tailscale — メッシュVPN。スマホとマシンがプライベートネットワーク上で互いを認識します。ポートフォワーディングもパブリックIPも不要。個人利用は無料です。

• Termius — Android/iOS用SSHクライアント。キー認証、永続セッション、Tailscaleアドレスに対応。無料ティアで十分です。

• tmux — ターミナルマルチプレクサ。SSH切断後もセッションは存続します。

# 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

tmuxセッションが存在する限り、ボットは稼働し続けます。SSHの切断では死にません。tmuxセッションを閉じるとボットも終了します——これが設計です。

ワークフロー: バスに乗っているとき、スマホでTermiusを開き、Tailscale経由でマシンにSSH接続し、tmuxセッションにアタッチ——ClaudeがTelegram上で稼働します。Termiusを閉じてもtmuxセッションは持続し、ボットは動き続けます。後でどこからでも再開できます。

権限の処理

ツール呼び出しはTelegramの承認/拒否ボタンとして表示されます。セッションは--permission-mode defaultで実行されるため、破壊的な操作(ファイル書き込み、シェルコマンド)は実行前に明示的なタップが必要です。

アーキテクチャの決定

なぜセッションピン型なのか?

常駐ボットは、リソースを消費し、古いコンテキストに基づいて行動する可能性のある常駐Claudeセッションを意味します。ピン設計では、必要なときにボットが稼働し、不要なときは停止します。これは制限ではなく、機能です。

なぜ2つのファイル(server.ts + proxy.ts)なのか?

サーバーはsystemdユニットとして実行され、Telegramのポーリング接続を保持します。プロキシはClaudeによってstdio MCPトランスポートとして起動されます。分離することで:

• サーバーはClaudeから独立して再起動できる

• プロキシは実行中のサーバーに再接続できる

• Claudeセッションの再起動中にポーリング状態が失われない

なぜWebhookではないのか?

WebhookにはパブリックURL、TLS、ポートフォワーディングが必要です。ロングポーリングはどこでも動作します——NATの内側、ラップトップ、VPS。マシン自体以外のインフラはゼロです。

トークンにつき1つのポーラー

TelegramのBot APIは、2つのプロセスが同じトークンをポーリングすると409 Conflictを返します。ロックファイル(pinned.lock)がポーラーを厳密に1つに制限します。セッションがクリーンアップなしでクラッシュした場合、次のtgpinが古いPIDを検出してロックを回収します。

ファイル

ライセンス

Apache-2.0(上流のClaude Code Telegramプラグインと同じ)。

連絡先

• GitHub: Swigler