Claude Code ↔ Telegram ブリッジ

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

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

Related MCP server: tsgram-mcp

セキュリティパッチ

上流プラグインには情報開示の問題があります: /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