Claude Code Telegram Kit

これもまた別のTelegramブリッジではありません。 Anthropic公式のClaude Code Channelは受信を処理します。このキットは、公式が行わない2つのことを修正します：Telegramのパーサーを生き抜くMarkdown、および携帯電話からのコンテキストリセットです。

研究プレビューインフラストラクチャ。機密データを含むマシンに接続する前に、セキュリティモデルを確認してください。

同じMarkdownドキュメント、両方のパス。公式のreplyツールはデフォルトでformat: "text"であるため、マークアップはリテラルとして届きます。そのmarkdownv2モードはMarkdownV2のエスケープをモデルに委ねるため、一文字でも欠けると送信に失敗します。send_replyはドキュメントをエスケープせずに受け取り、自らトランスポートを選択します。（図は両方のパスからレンダリングされたものであり、デバイスのスクリーンショットではありません。）

なぜこれが存在するのか

他のすべての「Claude Code + Telegram」プロジェクトは、公式Channelを置き換えます：独自のポーラー、独自のセッション管理、独自のペアリング。これはそうではありません。受信ポーリング、送信者ペアリング、添付ファイル、権限リレーはAnthropicのプラグインに任せます。このキットは、公式に加えて2つの制限付きアウトバウンド/コントロール機能を追加します。第二のgetUpdatesコンシューマはありません。

• Telegram Renderer MCP — 1つの標準的なsend_reply(raw Markdown)ツールで、決定論的なRich Message vs MarkdownV2ルーティング、および永続的な障害時のみフォールバックを行います。

• Session Control MCP — 承認ゲート付きの/resetパスで、PID 1が実行するルート所有、フェイルクローズのローカルリセットヘルパーによってバックアップされます。

両方のギャップは上流でオープンです。このキットは暫定的な回答です：

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

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

クイックスタート

公式の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 を自分のパスに置き換えてください。GFMテーブルを含むメッセージを送信してください。レンダラーは mode: rich と報告するはずです。

レンダラーは単独で動作します。/reset はさらにルートヘルパーが必要で、session-control READMEのexact-commit手順で別途インストールします。

本番デプロイ、ロールバック、検証については、このセクションではなく、operations runbookに従ってください。

アーキテクチャ

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とprocfsが/procにマウントされた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、トランスクリプト、サービス固有のパス、またはライブリセット設定をコミットしないでください。

プロジェクトステータス

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

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

ライセンス

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

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