Telegram (kotlogramme)

kotlogramme-cli

kotlogramme ファサードを基盤に Kotlin で作られた、コマンドラインの Telegram クライアントです。

端末で実際に役立つスクリプト可能なクライアントであることと、kotlogramme のすべての機能を使い、実際のアプリケーションで不足している部分を見つけるリファレンス実装であることの、両方を目指しています。

ステータス：利用可能です。 フェーズ 1〜9 を実装済みです。認証、設定、ダイアログ、履歴、メッセージの送信と編集、メディアとファイル、連絡先、検索、チャットメンバー、ダイアログフォルダー、ライブ更新、対話型シェル、管理者権限、スタンプ、インライン機能に対応しています。現在のリリースは v0.11.1 で、ファット JAR とディストリビューションが含まれています。JitPack の kotlogram v0.9.15 タグを基にビルドされています。元のフェーズ以降に追加された機能： download-media、サーバー側のメディア種別フィルターに対応した list-files、send-file のアップロード進捗バー。受信メッセージは書式を維持して表示され、メッセージのインラインボットは @username に解決されます。リリースに含まれる機能については docs/features.md を、残っている項目（アルバム送信、進捗表示付きの分割ダウンロード、ブロック、ボットでも安全な数値ピア検索）については docs/plan.md を参照してください。

クイックスタート

kotlogramme config set --api-id <id> --api-hash <hash>   # from my.telegram.org
kotlogramme login --phone +491700000000                  # prompts for the code, then 2FA if set
kotlogramme dialogs --limit 20
kotlogramme history @some_chat --limit 50
kotlogramme send @some_chat "hello from the terminal"
kotlogramme send-file @some_chat clip.mp4                  # detects the kind: a streamable video
kotlogramme send-file @some_chat clip.mp4 --no-detect       # ...or send the raw bytes as a document
cat photo.png | kotlogramme send-file @some_chat - --name photo.png   # ...or pipe the bytes on stdin
kotlogramme list-files @some_chat --kind video             # the chat's videos, filtered by Telegram
kotlogramme download-media @some_chat 12345                # save a message's media, named after it
kotlogramme stickers                                       # installed sticker sets
kotlogramme listen                                         # follow new messages
kotlogramme shell                                          # interactive REPL

listen [--once] [--all] [--json] [--chat <id|@username|title>] はライブ更新ストリームを追跡します。既読通知、連絡先のステータスなど、メッセージを伴わない更新は --all を指定するまで非表示になります。指定すると、それらの内容が JSON として出力されます。--chat を指定すると、そのチャットのメッセージだけが表示されるため、listen --once --chat @ada はそのチャットの次のメッセージを待ち受けます。--once は最初に表示された更新の後に停止し、--json は 1 行につき 1 つのオブジェクトを出力します。Ctrl-C でコマンドを正常に終了できます。ストリームの追跡にはライブラリ独自のバックグラウンド更新ループを使用します。このループは短い間隔でポーリングし、停止時にはスレッドを終了するため、停止にかかる時間はライブラリの 30 秒ではなく、最大でも短いポーリング 1 回分です。

list-files <peer> は、履歴をスキャンするのではなく、Telegram 側でメディア種別を絞り込んでチャットのファイルを一覧表示します。そのため、履歴の読み込みが済んだ範囲だけでなく、チャット全体を対象にできます。--kind はフィルターを指定します（photo、video、photo-video、document、audio、voice、gif、animation）。--limit はページの上限を設定し、--total はチャット内のファイル数だけを出力します。

download-media <peer> <message-id> [<target>] はメッセージのメディアをローカルファイルに書き込みます。保存先を指定しない場合は、メディア本来の名前をファイル名として使い、名前がない場合はメッセージ ID を使って作業ディレクトリに保存します。存在しない親ディレクトリは作成され、既存のファイルは上書きされます。コマンドはファイルのパスとバイト数を出力するため、スクリプトからどちらも読み取れます。

各コマンドは、デフォルトではテーブル形式で表示します。グローバルオプションの --plain と --json はコマンドの前に指定し（kotlogramme --json history @ada）、その実行に限り、タブ区切りのプレーンテキストまたは JSON に切り替えます。--table はテーブル形式を強制します。config set --format を使うと、デフォルトの形式を保存できます。JSON では、出力の各行が 1 つの JSON 値になります。テーブルはオブジェクトの配列、メッセージは {"message": "..."}、件数は {"count": N} となり、一覧表示が途中で打ち切られた場合は最後に {"next_after": "..."} が出力されます。import-contacts --from-json FILE（標準入力の場合は -）では、{"phone", "first_name", "last_name"} オブジェクトの JSON 配列を指定します。テーブルは端末の幅に合わせて折り返されます。コマンドの前に --table-width N を指定すると幅を設定できます（0 は折り返しなし）。これを使えば、折り返されたテーブルをファイルに出力できます。kotlogramme doctor は API 認証情報がなくても、ネイティブライブラリ、Telegram スキーマ、端末ライブラリ、設定、ネットワークを確認します。認証情報が設定されている場合は、アカウントも確認します。

AI アプリケーションから使用する（MCP）

kotlogramme mcp は、Model Context Protocol サーバーとして、stdin と stdout 経由でクライアントを実行します。kotlogramme login で一度ログインしたら、AI アプリケーションにコマンドを登録します。たとえば、Claude Desktop の claude_desktop_config.json では次のように設定します。

{ "mcpServers": { "telegram": {
  "command": "C:\\Tools\\console\\kotlogramme.exe",
  "args": ["mcp"],
  "env": { "TG_API_ID": "...", "TG_API_HASH": "..." } } } }

Claude Code の場合は、claude mcp add telegram -- kotlogramme mcp を実行します。デフォルトでは読み取り専用です。チャットの一覧表示、メッセージの読み取りと検索、連絡先、メンバー、セッションの一覧表示、次のメッセージの待機ができます。--access read-write を指定すると、メッセージの送信、編集、転送、リアクション、ピン留めが可能になります。--access full を指定すると、メッセージの削除、人の削除とブロック、管理者権限の変更、セッションの終了も可能になります。書き込み可能な AI アプリケーションはあなたとして動作し、実在する人々に働きかけるため、目的を達成できる最も低い権限レベルを選んでください。 --files-dir <directory> を指定すると、そのディレクトリ内のファイルを送信し、ダウンロードをそのディレクトリに保存するツールが追加されます。ディレクトリ外にはアクセスしません。メッセージ本文は他の人が送信するため、サーバーはモデルに対し、メッセージを指示ではなくデータとして扱うよう伝えます。ツールの一覧はdocs/features.mdにあります。

**AI エージェント：**ユーザー向けにサーバーをダウンロードしてインストールするには、docs/agent-install.mdに従ってください。

アップロードの進捗状況

send-file は、データの送信中に1行の進捗バーを表示し、割合、送信済みのバイト数、合計バイト数、現在の転送速度を示します。

kotlogramme send-file @some_chat clip.mp4

出力先がターミナルの場合はデフォルトで進捗バーが有効になり、パイプまたはリダイレクトの場合は無効になるため、スクリプトの出力に復帰文字は入りません。--progress で強制的に有効にし、--no-progress で無効にできます。両方が指定された場合は、--no-color が --color より優先されるのと同様に、--no-progress が優先されます。バイトデータをアップロードするのは send-file だけなので、これらのフラグを使えるのも send-file だけです。--no-color を指定すると、進捗バーはプレーンな ASCII で表示されます。最初の更新前にアップロードが完了した場合、進捗バーは表示されません。アップロードが完了した場合、失敗した場合、または Ctrl-C で中断された場合のいずれも、行は消去されます。

Telegram は最初のパートを送信する前に合計サイズを通知される必要がありますが、パイプには長さがないため、パイプ入力はアップロード開始前に一時ファイルへスプールされます。スプールファイルにより、cat photo.png | kotlogramme send-file @some_chat - ではパイプから渡されたバイトデータを正確にアップロードでき、実際の合計サイズも得られるため、パイプ経由のアップロードでも割合が表示されます。スプールファイルは、アップロードがどのように終了した場合も、その終了後に削除されます。唯一のコストは、バイトデータがシステムの一時ディレクトリを一度経由することです。メモリではなくディスク I/O が発生しますが、アップロード自体は引き続きチャンク単位でストリーミングされ、ファイル全体がヒープに保持されることはありません。

クライアントの入手

現在のリリースはv0.11.1です。GitHub Release には、以下の JVM アーティファクトと、5つの単一ファイルのネイティブ実行ファイルが含まれています。

• kotlogramme-all.jar - 実行可能な単一のファット JAR です。JDK 25 で実行してください。

  java -jar kotlogramme-all.jar --help
  

• kotlogramme-0.11.1.zip - distZip ディストリビューションです。解凍して、kotlogramme-0.11.1/bin/kotlogramme（Windows の場合は kotlogramme-0.11.1\bin\kotlogramme.bat）を実行してください。JAR とその依存関係は lib/ に格納されています。

• 単一ファイルのネイティブ実行ファイル — kotlogramme-0.11.1-windows-x86_64.exe および kotlogramme-0.11.1-{linux,macos}-{x86_64,aarch64}。ダウンロードしたファイルを直接実行してください。Linux/macOS では、最初に chmod +x を実行してください。JRE、JDK、インストーラーは不要です。サポートライブラリは Wrappe によって組み込まれ、一時キャッシュに展開されます。ネイティブ要件を参照してください。

要件

• JVM ディストリビューションの実行には JDK 25 が必要です。ネイティブ実行ファイルには Java は不要です。以下のすべてのライブラリと、ホスト用のネイティブ Telegram ライブラリはディストリビューションに同梱されています。ビルド時には、ツールチェーンリゾルバーを使って Gradle が JDK を自動取得できます。
• Telegram API の認証情報：https://my.telegram.org で取得した api_id と api_hash を、kotlogramme config set または TG_API_ID／TG_API_HASH 環境変数で設定します。
• サインインに使用する Telegram アカウント（kotlogramme login）、またはボットトークン。ダイアログ、履歴、チャット内のファイルを読み取るには通常のアカウントが必要です。
• サポート対象プラットフォーム：x86_64 または aarch64 の Windows、Linux、macOS。
• Telegram へのネットワークアクセス。

依存関係

クライアントは以下のライブラリを使用して構築されています。ディストリビューションは自己完結型で、すべて kotlogramme-all.jar に同梱されているため、個別にインストールする必要はありません。各ライブラリのライセンスはそれぞれ適用されます。

• com.github.J0s3f:kotlogram — このクライアントが使用するファサードです。タグで固定されています（ファサードのバージョンの選択を参照）。grammers と6つのネイティブ Telegram ライブラリが含まれています。
• Clikt 5.1.0 — コマンドラインの解析、オプション、ヘルプ。
• JLine 4.4.6 — 対話型シェル、補完、ターミナル出力。
• kotlinx.serialization 1.11.0（JSON）— --json 出力形式と設定ファイル。
• SLF4J 2.0.20（シンプルバインディング）— ログ記録。レベルを設定しない限り静かに動作します。

ビルドと実行

./gradlew build          # compile and run the offline test suite
./gradlew installDist    # build the runnable distribution
build/install/kotlogramme/bin/kotlogramme --help

Windows では、gradlew.bat と生成された build\install\kotlogramme\bin\kotlogramme.bat を使用します。

Wrappe とともにパッケージ化されたスタンドアロンの GraalVM ビルドは、Windows x86_64 および Linux／macOS x86_64／ARM64 で、JRE や JDK なしで実行できます。

.\scripts\build-native-windows.ps1
build\distributions\kotlogramme-0.1.0-SNAPSHOT-windows-x86_64.exe --help

スクリプトは既定で C:\Tools\graalvm-jdk-25.0.4+7.1 を使用します。ビルドには MSVC C++ ツールと Windows SDK も必要です。ネイティブクライアントをコンパイルし、Wrappe を使ってポータブルな実行ファイルを1つ作成してテストします。CI では、5つすべてのネイティブターゲットで Liberica NIK 25 を使用します。リリースには、同梱 jar と Java zip に加えて、単一ファイルの実行ファイルが含まれます。Windows ARM64 では JVM ディストリビューションを使用します。セットアップ、プラットフォーム要件、検証については docs/native-image.md を参照してください。

ファサードのバージョンの選択

クライアントは JitPack から解決されるファサードの v0.9.15 タグに依存しています。別のバージョンに固定するには、明示的に指定します。公開済みのファサードタグであれば、どれでも使用できます。

./gradlew test -PkotlogrammeVersion=<tag>

ドキュメント

• docs/plan.md — 実装計画の正本です。
• docs/architecture.md — コードの構成と、その理由です。
• docs/decisions.md — 設計上の決定とその根拠です。
• docs/features.md — 実際に提供されるユーザー向け機能です。
• docs/native-image.md — スタンドアロンのネイティブパッケージのビルドと検証です。
• AGENTS.md — 人間とエージェント向けのエンジニアリング規則です。

安全性と制限

• 非公式です。 kotlogramme は Telegram によって開発、承認、サポートされていません。ボットとしてではなく、ご自身のユーザーアカウントとして MTProto 経由でサインインするため、Telegram のAPI 利用規約が適用されます。一括または自動でのメッセージ送信、参加、ユーザー追加を行うと、フラッド待機やアカウント制限が発生することがあります。そのリスクはご自身で負うことになります。
• セッションファイルはアカウントそのものです。 設定ディレクトリ内のセッションファイルを読み取れる人、またはご自身としてプログラムを実行できる人は、ご自身と同じすべての権限を持ちます。非公開にし、決してコミットしたり共有したりしないでください。API ID とハッシュについても同様です。
• アクセスレベルはこのサーバーの制限であり、Telegram の制限ではありません。 --access read-only を指定するとツールによる変更を防げますが、プロセス内ではセッション自体が引き続き完全な権限を保持します。
• AI が読み取る内容はお使いのマシンの外部に送られます。 MCP モードでは、ツールが返すメッセージ、名前、ファイル名が AI アプリケーションとそのプロバイダーに渡されます。チャットとアクセスレベルは適切に選択してください。
• メッセージの内容には悪意のあるものが含まれる可能性があります。 メッセージは他の人が作成するもので、モデルへの指示を試みることがあります。サーバーの指示にはその旨が記載されていますが、どのような指示も保証にはなりません。見知らぬ人からメッセージを受け取るアカウントでは read-only を優先し、書き込みツールや削除ツールが実行しようとしている内容を確認してください。
• 接続は一度に1つだけです。 同じセッションで mcp と別の kotlogramme コマンド、シェル、listen を同時に実行しないでください。Telegram が1つのログインによる並行利用を拒否することがあります。
• 保証はありません。 下記の Apache-2.0 ライセンスをご覧ください。

ライセンス

このプロジェクトは Apache-2.0 ライセンスのもとで公開されています。詳細は LICENSE をご覧ください。このプロジェクトは、同じライセンスのもとで公開されている kotlogramme ファサードをベースにしています。kotlogramme はさらに grammers に依存しており、grammers は Apache-2.0 または MIT のデュアルライセンスです。grammers の通知が引き続き正式なものとなります。