Claude Code Telegram Kit

また別のTelegramブリッジではありません。 Anthropic公式のClaude Code Channelは受信専用です。このキットは、Telegramのパーサーを生き抜くMarkdownと、スマートフォンからのコンテキストリセットという、公式が対応していない2つの機能を補完します。

研究プレビュー段階のインフラです。貴重なデータがあるマシンに接続する前に、セキュリティモデルを確認してください。

同じMarkdownドキュメントを、両方の経路で表示したものです。公式のreplyツールはデフォルトでformat: "text"を使用するため、マークアップがそのまま表示されます。また、markdownv2モードではMarkdownV2のエスケープ処理がモデルに委ねられるため、1文字でもエスケープを忘れると送信に失敗します。send_replyはドキュメントをエスケープせずに受け取り、自動的に適切な転送方式を選択します。（図は両方の経路からレンダリングされたものであり、デバイスのスクリーンショットではありません。）

なぜこれが必要か

他の「Claude Code + Telegram」プロジェクトは、公式Channelを置き換えます。独自のポーリング、独自のセッション管理、独自のペアリングを行います。このキットはそうではありません。受信ポーリング、送信元ペアリング、添付ファイル、権限リレーはAnthropicのプラグインに任せます。このキットは、2つの限定された送信/制御機能をその横に追加するものであり、2つ目のgetUpdatesコンシューマーは必要ありません。

• Telegram Renderer MCP — 1つの標準的なsend_reply(raw Markdown)ツール。決定論的なリッチメッセージ vs MarkdownV2ルーティング、パーマネントのみのフォールバック、👀 → 👍/👎の処理リアクションを備えています。

• Session Control MCP — 承認ゲート付きの/resetパス。確認された承認リアクションを確定し、その後、PID 1が実行するルート所有、フェイルクローズのローカルリセットヘルパーに実行を引き継ぎます。

両方のギャップは上流で認識されています。このキットはそれまでの暫定的な回答です。

• anthropics/claude-code#39684 — リモートからコンテキストをクリアまたはリセットする方法がない

• anthropics/claude-code#36622 および claude-plugins-official#774 — MarkdownV2のparse_modeのリクエスト

Related MCP server: tsgram-mcp

クイックスタート

公式のtelegram@claude-plugins-officialプラグインがすでにペアリングされ、動作している必要があります。

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)"

次に、examples/.mcp.json、examples/telegram-settings.json、examples/CLAUDE.mdをClaudeプロジェクトにコピーし、USERを自身のパスに置き換えてください。examples/access-ux.jsonを公式Channelのaccess.jsonにマージして、最初の👀確認応答を有効にします。GFMテーブルを含むメッセージを送信してください。レンダラーはmode: richを報告し、👀を👍に置き換えるはずです。

レンダラーは単独で動作します。/resetはさらにルートヘルパーが必要であり、session-control READMEの正確なコミット手順によって別途インストールされます。

本番環境へのデプロイ、ロールバック、検証については、このセクションではなく運用ランブックに従ってください。

アーキテクチャ

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

レンダラーと制御MCPは、公式Channelのトークンとaccess.jsonの権限を再利用します。これらにはdmPolicy: allowlist、セキュアな0600の状態ファイル、および正確な宛先メンバーシップが必要です。

設計不変条件

以下の5つが影響範囲を定義します。

• ボットトークンあたり1つのTelegram getUpdatesコンシューマー。

• 任意のBot APIメソッドツールはなし。

• 任意のシェルコマンドツールはなし。

• タイムアウト、429、5xx応答、および不明な結果は再送信をトリガーしない。

• PID 1が、Claudeプロセスが終了される前にリセット実行を所有する。

完全なセットはdocs/design-invariants.mdにあります。

リポジトリ構成

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

要件

• systemdと/procにマウントされたprocfsを備えたLinux

• Claude Code 2.1.234以降

• Bun 1.3.14以降

• Python 3.11以降

• Anthropic公式のtelegram@claude-plugins-officialプラグイン

インストールモデル

変更可能な開発チェックアウトから本番環境を実行しないでください。バージョン管理されたリリースディレクトリに正確なコミットをインストールしてください。

~/.local/share/claude-code-telegram-kit/
  releases/<git-sha>/
  current -> releases/<git-sha>
  previous -> releases/<previous-sha>

scripts/deploy_local.pyは、Python 3.11互換のリンクなし/トラバーサルなしの抽出器でGitアーカイブを展開し、本番依存関係をインストールし、リリースレシートを検証し、current/previousをアトミックにスワップします。ルート所有のファイルをインストールすることはありません。

python3 scripts/deploy_local.py status
python3 scripts/deploy_local.py rollback

Telegramの認証情報と許可リストはClaudeの状態ディレクトリに、リセット設定はルート所有で/etc/claude-code-telegram-kit/の下に保持してください。

セッションリセット

ローカル復旧権限は以下の通りです。

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

オプションのTelegram /resetコマンドは、薄いMCPフロントエンドです。すでにメッセージを受信できないClaudeプロセスを復旧することはできません。緊急時のパスとして、ローカルヘルパーを利用可能にしておいてください。

開発

bun install --frozen-lockfile
bun run check
bun audit

セキュリティ

デプロイ前にSECURITY.mdをお読みください。ボットトークン、チャットID、トランスクリプト、サービス固有のパス、またはライブのリセット設定を決してコミットしないでください。

プロジェクトステータス

このコードは、実際に稼働しているデプロイメントから抽出され、クリーンルームの公開リポジトリに一般化されたものです。1.0.0より前はAPIが変更される可能性があります。

初期リリースはソースのみです。ワークスペースパッケージはprivateとマークされており、npmには公開されていません。バージョン管理されたデプロイスクリプトを使用して、正確なGitコミットからインストールしてください。

ライセンス

Apache-2.0。LICENSE、NOTICE、およびTHIRD_PARTY_NOTICES.mdを参照してください。リリース手順: RELEASING.md

このプロジェクトは独立したものであり、AnthropicやTelegramによって承認されているものではありません。