WireCat Telegram

tg — AI エージェント向け Telegram CLI

Telegram アカウントのすべてをターミナルで操作できます。パソコン上で検索でき、Claude Code、 Codex、Cursor などのエージェントですぐに使えます。利用範囲は自分で設定できます。

ドキュメント · 使用例 · WireCat

会話の例（登場人物は架空で、出力は説明用です）：

You:    Use tg CLI. What did I promise anyone in the last three days?
Agent:  (runs tg personal review 'date>3d': 12 chats)
        I owe
        · Alice Example — the invoice by Friday. "Alice Example", 24.09
        Waiting on others
        · Bob Sample — the mock-up by 25.09. Not in "Design" yet
You:    Remind Bob about the mock-up.
Agent:  Draft: "Hi Bob, how is the mock-up going?" Send it?
You:    Yes.

クイックスタート

npm install -g @wirecat/tg-cli    # or: bun add -g @wirecat/tg-cli; pnpm: see docs/installation.md
tg skill install --for all        # the agent skill, for Claude Code, Codex and Gemini CLI
tg personal setup                 # app registration and login
tg personal inbox                 # other people's unread messages, in every chat; nothing is marked read

グローバルインストールではエージェントスキルはインストールされません。tg personal setup から追加するか、tg skill install --for all を実行してください。npm が、インストールスクリプトがブロックされた、または「まだ allowScripts の対象になっていない」（@wirecat/tg-cli、 better-sqlite3）という警告を表示する場合がありますが、問題ありません。許可する必要はありません。理由はこちら。 Windows で tg が見つからない場合は、新しいターミナルを開くか、 インストールガイドの PowerShell インストーラーを使用してください。

5 分ほどで完了します。tg personal setup は my.telegram.org で自分の Telegram アプリを登録し、QR コードでログインして、最初のチャットを確認し、エージェントスキルをインストールします。古い履歴のダウンロードは別の手順です。

macOS、Linux、Windows で、Node 22.19+ または 24+、あるいは Bun が必要です。インストールせずに試すには、 npx @wirecat/tg-cli --help を実行してください。

詳細：インストールガイド · wirecat.dev

何ができますか？

状況を把握する。 「tg CLI を使って。今朝から何が届いた？返信を待っているのは誰？」

tg personal inbox
tg personal review 'date>1d'

何でも検索する。 「tg CLI を使って。Alice と会場について合意したのはいつ？」 — 日付と該当メッセージを含む回答が得られます。

tg personal search all "venue"                # messages and notes on this computer, and Telegram's own search

デフォルトでは検索語句は Telegram のサーバー検索にも送信されます。検索をこのパソコン内にとどめるには --offline を追加してください。

約束を確認する。 「tg CLI を使って。何を約束した？まだ何を待っている？」 tg personal review を実行すると、前回の確認以降に話した内容が、自分のメッセージも含めて、1 回の呼び出しでまとめて取得できます。

tg personal review --new                      # what changed since the last review --new

グループを運営する。 「tg CLI を使って。Hiking で、誰も答えていない質問はどれ？」

tg personal review chat:Hiking --unanswered
tg personal chats events "Hiking" "time>=7d"  # who joined, left, was added or removed

詳細：スケジュールと各種制限を含むレシピ · wirecat.dev

AI エージェント向けに構築

あなたのエージェント。あなたの Telegram。あなたのルール。

• ターミナルを備えたエージェント（Claude Code、Codex、Gemini CLI など）は、自ら tg コマンドを実行します。同梱のスキルで使い方を確認できます。tg personal setup --agent … または tg skill install でスキルを設定でき、ログイン前には tg skill show で内容を表示できます。
• ターミナルを備えていないアプリ（Claude Desktop、Cursor、その他の MCP クライアントなど）は、tg personal mcp serve に接続します。すぐに使えるプロンプトが付属しています：/catch-up、/review、/reply、/find、/open-tasks、/link-conversations。

tg personal mcp add claude-code  # or: tg personal mcp add codex
tg personal mcp config      # the entry for Claude Desktop, Cursor and others

プロファイルはデフォルトで送信が許可されているため、mcp add は最初に停止します。プロファイルの権限を確認してから、もう一度 --allow-writes を付けて実行してください。

詳細：MCP サーバー · wirecat.dev のドキュメント

tg を選ぶ理由

• ボットだけでなく、アカウント全体に対応。 履歴を含むすべてのチャット、グループ、チャンネル、連絡先を扱えます。tg はあなたの端末のひとつです。
• ローカルファーストの検索。 読み取った内容はすべてコンピューターに保存されます。検索ではそのコピーを調べ、デフォルトでは Telegram 独自の検索も利用します。--offline を指定すると、検索はコンピューター上で完結します。
• エージェント向けの設計。 呼び出しごとにひとつの操作を行い、--json を指定すると毎回同じ JSON 形式で結果を返します。失敗の種類ごとに固定の終了コードを用意し、MCP サーバーとスキルも備えています。
• デフォルトで安全。 読み取りによって既読になることはありません。プロファイルで、エージェントが実行できる操作、送信できるチャット、1 時間あたりのメッセージ数（デフォルトでは 30 件）を決められます。送信結果が不明な場合は tg がその旨を伝え、Telegram で二重配信されない再試行コマンドを提示します。
• Bot API にも全面対応。 便利なボットコマンドに加え、185 個すべてのメソッドを利用できます。

詳細：他のツールとの比較 · wirecat.dev のドキュメント

あなたのアカウント

tg は、あなたの端末のひとつとして、あなたの名前で動作します。ボットではありません。自分で登録したアプリを使い、クライアントアプリ向けの Telegram 独自 API である MTProto 経由で Telegram と通信します。あなたのチャットとその履歴、グループ、チャンネル、連絡先を参照できます。

tg personal chats list --limit 5
tg personal messages list "Book club" --limit 20
tg personal messages send "Book club" "Call at 3?" --reply-to <id>
tg personal reactions add "Book club" <id> 👍
tg personal messages send me "Call mum" --at-time 2h  # a reminder in Saved Messages in two hours
tg personal messages send "Book club" "The minutes" --file minutes.pdf
tg personal messages download "Book club" <id> --output-dir ~/Downloads
tg personal messages transcribe "Book club" <id>  # a voice message as text

• 読み取り。 チャット、履歴、前後のメッセージを含む 1 件のメッセージ、すべてのチャットにおける他の人の未読メッセージ（tg personal inbox）、前回のレビュー以降のすべての内容（tg personal review）、届いた新着メッセージ（tg personal watch）、メッセージのファイル、テキスト化した音声メッセージ。
• 書き込み。 Markdown、返信、ファイル、写真、動画、音声メッセージ、サイレント送信や予約送信（このコンピューターの電源が切れていても送信されます）、編集、転送、ピン留め、リアクション、投票、削除。自分だけ、または全員から削除できます。
• コンピューター上での音声処理。 Premium アカウントでは Telegram が音声を文字起こしします。tg はこのコンピューター上で音声モデルを実行することもでき、そのモデルは要求されたときにのみダウンロードされます。
• 連絡先とアカウント。 連絡先の追加、名前変更、ブロック、インポート、相手に付けた自分用の別名やメモ、ログイン中のアカウント、アカウントにログインしているすべての端末を確認できます。
• 個人について。 相手のプロフィール、最終ログイン時刻、共通の各チャットにおける相手のメッセージ、アカウントがボットまたはスパマーのように見えるかどうかを確認できます。

詳細：tg の使い方 · wirecat.dev のドキュメント · 個人について · wirecat.dev のドキュメント

ログインとプロフィール

各ユーザーがそれぞれ自分の Telegram アプリを登録します。tg personal setup または tg personal session start を実行すれば、自動で登録できます。アプリのキーはシステムのキーリングに保存され、セッションファイルはそのユーザーだけが読み取れます。

tg personal session start               # a QR code: Settings → Devices → Link Desktop Device
tg personal session start phone         # or a phone number, the code and your 2FA password
tg personal session start qr            # without a terminal (an agent): the QR code as text to paste into the chat
tg personal account show                # who you are logged in as
tg account list                         # every profile here, and who each is logged in as

アカウントが複数ある場合は、プロフィールも複数あります。プロフィール名は最初の単語であり、オプションではありません。

tg personal chats list     # profile "personal"
tg work chats list         # profile "work"
export TG_PROFILE=work     # or for the whole shell session

tg がプロフィールを選ぶことはありません。プロフィールが1つしかない場合も同じです。アカウントを使用するコマンドでプロフィール名を指定しないと、処理を停止して、このコンピューター上のプロフィール一覧を表示します。プロフィール名を指定するか、シェルセッション全体に適用する場合は TG_PROFILE を設定してください。

詳細：ログインとセッション · wirecat.dev のドキュメント · プロフィール · wirecat.dev のドキュメント

ローカルストアと検索

tg が読み取るデータはすべて、コンピューター上のローカルストアに保存されます。検索はデフォルトでローカルストアと Telegram の両方を対象に行います。--offline を指定すると、接続せずにローカルストアから回答します。

tg personal search messages 'contract chat:"Project Alpha"'
tg personal search messages "contract" --backend archive  # local only
tg personal messages sync "Project Alpha" --last 5000 --background
tg personal store export "Project Alpha" --format markdown --output alpha.md
tg personal messages evidence "Project Alpha" --json  # bounded evidence for a chat brief
tg personal server install                         # keep the store current as a systemd or launchd service
tg personal store backup ~/tg-backup.db            # a copy, safe while the store is in use

単語、人、日付、ファイル、リンク、タグで検索したり、検索を保存したり、トピックごとに議論を探したりできます。

詳細：検索 · wirecat.dev のドキュメント · ローカルストア · wirecat.dev のドキュメント

管理するグループ

tg personal review chat:Hiking --unanswered   # questions nobody answered in 24 hours
tg personal chats events "Hiking" "time>=7d"  # who joined, left, was added or removed, and by whom
tg personal chats members list "Hiking" --all     # everyone, with their role and when they were last seen
tg personal topics list "Hiking"                  # a forum group's topics, newest activity first
tg personal chats inspect https://t.me/+AbCdEf    # where an invite link leads, without joining
tg personal chats create "Hiking 2027" @alice_example  # a new group, with the people you name
tg personal stats chats show "Hiking"             # group activity

グループ名の変更、メンバーや管理者の追加と削除、参加リクエスト、招待リンク、フォーラムのトピック、リンク・転送・大量投稿に関するモデレーションルールも、コマンドで操作できます。

詳細：管理するグループ · wirecat.dev のドキュメント

ボット

tg personal bot は、Telegram 公式の Bot API と @BotFather から取得したトークンを使ってボットを操作します。複数のボットを登録できます。それぞれに任意の名前を付け、その名前をコマンドの最初の単語として使います。

tg sales bot auth set                    # the token, at a hidden prompt; Telegram checks it first
tg sales bot auth show                   # which bot it is
tg sales bot recipients add user:<id>    # the bot may write only here
tg sales bot messages send "Team" "Build is ready" --file report.pdf
tg sales bot api --help                  # every Bot API method, each with its fields
tg personal bot list --check             # every bot on this computer

• すべての Bot API メソッド。 tg <bot> bot api <method> には、ネイティブのフィールドフラグまたは JSON 本文を指定できます。
• 名前ごとに1つのトークンをキーリングに保存し、自分のログインとは別に管理します。CI では TG_BOT_TOKEN を使用できます。トークンが表示されることはありません。エラー時も、--trace を指定した場合も、実行記録にも表示されません。
• 宛先と操作記録。 各ボットには、書き込み可能なチャットのリストと、テキストを含まない操作記録があります。
• メッセージ、管理者、メンバー、ボタン、メニュー、Webhook — 送信、編集、削除、ピン留めに対応しています。bot chats admins、bot callbacks answer、bot commands、bot webhooks を使用します。
• 履歴。 bot watch はボットのチャットで発生した内容を表示し、保存します。bot messages sync は、過去のチャンネルとスーパーグループのメッセージをインポートします。

詳細：Telegram ボット · wirecat.dev のドキュメント

エージェントのセットアップ詳細

スキル。 Claude Code は ~/.claude/skills/tg-cli/ を読み込みます。Codex、Gemini CLI、ローカルの Cursor は ~/.agents/skills/tg-cli/ を読み込みます。エージェントがスキルを認識しない場合は、新しいエージェントセッションを開始してください。

tg skill install --for all        # both folders, without logging in
tg skill show                     # the complete instructions, without installing them

MCP サーバー。 コマンドは、引数と現在の利用可否を含め、常に確認できます。どのコマンドを実行できるかは、プロフィールの permissions で決まります。readonly は書き込みを禁止します。ask の場合、サーバーは確認フォームを表示しないため、エージェントアプリで承認を設定してください。

claude mcp add tg -- tg personal mcp serve  # Claude Code, by hand
tg personal mcp check            # check the local MCP server

ブラウザーから。 ChatGPT またはブラウザー版 Claude は、ターミナルでワンタイムアクセスコードを使ってログインした後、トンネル経由で tg personal mcp serve --http --public-url <url> にアクセスします。

詳細：MCP サーバー · wirecat.dev のドキュメント · リモートアクセス · wirecat.dev のドキュメント

スクリプトとエージェント向けの出力

--json を指定すると、コマンドは JSON 値を 1 つだけ出力します。テーブル、色、ヒントは含まれません。別のプログラムが出力を読み取る場合も同様です。--jsonl は 1 行につき 1 つのオブジェクトを出力します。すべてのリストは次の形式です。

{ "items": [ … ], "page": { "limit": 20, "has_more": true }, "meta": { … } }

エラーは stderr に 1 行で出力され、stdout は空のまま、コマンドは固定の終了コードで終了します。4 はログイン、5 はプロフィールでこの操作が許可されていない場合、6 はチャットまたはメッセージが見つからない場合、8 は制限、9 は Telegram が時間内に応答しなかった場合、14 はメッセージが送信されたかどうか不明な場合です。tg commands --json はコマンドツリー全体を返します。部分的な読み取りやダウンロードでは終了コードが 0 になることがあります。JSON の complete を確認してください。

詳細：CLI の仕様 · wirecat.dev のドキュメント · すべてのコマンドと終了コード · wirecat.dev のドキュメント

設定と権限

tg personal config set permissions.messages readonly  # no change to messages from this profile
tg personal config set permissions.messages.send ask  # a question in the terminal before each send
tg personal config set sends_per_hour 10              # at most 10 sends an hour (30 by default)
tg personal recipients add "Book club"                # the first add turns the recipient list on
tg personal sends list                                # every attempt: sent, refused, failed or not known
tg personal config show                               # what is set, and where it came from

詳細：権限 · wirecat.dev のドキュメント · 設定 · wirecat.dev のドキュメント

制限

各プロフィールには、すべてのコマンド、バックグラウンドジョブ、サーバーで共有されるリクエスト頻度が 1 つ設定されているため、一括処理も Telegram の制限内に収まります。Telegram による短い待機時間はそのまま待ちますが、長い待機が発生した場合は、繰り返し実行せずに処理を停止します。

詳細：制限と待機時間 · wirecat.dev のドキュメント

セキュリティ

• セッションファイルはパスワードと同等の重要性があり、読み取れるのは自分のユーザーだけです。アプリキーはシステムのキーチェーンに保存されます。パスワード、ログインコード、電話番号を引数に取るコマンドはありません。
• ローカルストアには、読み取った内容の全文が暗号化されずに保存され、読み取れるのは自分のユーザーだけです。ログアウト後も残ります。盗難されたディスクからデータを守るには、ディスク全体の暗号化のみが有効です。
• コマンドからでも MCP 経由でも、すべての送信にはプロフィールの制限が適用され、ジャーナルに記録されます（メッセージ本文は記録されません）。--file は認証情報ファイル、CLI フォルダー、ローカルストアを拒否します。
• 名前、タイトル、メッセージ内の制御文字はテキストとして表示されるため、他人のテキストによってターミナルが制御されることはありません。
• 制限は、読み取ったメッセージによって送信を促されたエージェントを止めるためのものです。制限の回避を目的とするエージェントには対応できません。その場合は、エージェントをサンドボックス内または別のユーザーとして実行してください。

脆弱性の報告先：SECURITY.md。

詳細：セキュリティ · wirecat.dev のドキュメント

問題が発生した場合

tg personal doctor         # where the files are and whether a session is saved, without connecting
tg personal doctor --online  # check that the login works
tg personal chats list --trace  # each request to Telegram, with no text, names, phone numbers or keys
tg personal runs list      # recorded runs

詳細：症状別のトラブルシューティング · wirecat.dev のドキュメント · 診断 · wirecat.dev のドキュメント

他のツールとの違い

Telegram 公式アプリは人が使うためのものです。tg はスクリプトとエージェント向けに作られています。Telegram ボットが見られるのは追加されたチャットだけで、ボットとして発言します。一方、tg はあなた自身として、あなたのチャットを利用します。Telegram アカウントをエージェントに接続するオープンなツールはほかにもあります。tgcli、telegram-mcp、tdl です。

詳細：他のツールとの比較 · wirecat.dev のドキュメント

WireCat の一部

WireCat は、AI エージェント向けのオープンソースでローカル優先のコンテキストレイヤーです。まずは tg から始められます。max-cli を使えば、MAX メッセンジャーも同じローカルストアに追加できます。まずは Telegram から始めて、必要に応じてコンテキストを追加してください。あなたのコンテキストを、どのエージェントでも。

技術ドキュメント

すべてのページはwirecat.dev/en/docs/tgと docs/にあります。

ページ	内容
index · web	ドキュメントサイトのスタートページ：tg とは何か、最初の1分でできること、次に読むページ
installation · web	インストール方法、必要なもの、ファイルの保存先、アップグレードや削除の方法
usage · web	ログイン、閲覧、ページ送り、送信、スクリプトからの利用方法を順番に解説します
sessions · web	ログインの仕組み：QRコードまたは電話番号、my.telegram.org のアプリ、キーリング、プロフィール、ログアウト
archive · web	ローカルストアに保存される内容、データの取り込み、検索、エクスポート、最新状態の維持、バックアップ方法
search · web	メッセージを単語、送信者、チャット、日付、ファイル、リンク、タグで検索する方法、検索の保存、件数の確認
attachments · web	ファイルの送信、ダウンロード、閲覧、ドキュメントや画像からのテキスト抽出とその検索
rankings · web	メッセージと投稿者のランキング：指標、スコア、保存済みクエリ、根拠
topic-search · web	話題の内容からディスカッションを検索する方法、最新状態の維持、コンピューターの外部に送信される情報
query-language · web	すべての検索フィールド、演算子、プリセット、上限、JSON の応答
groups · web	運営しているグループの状況を把握する方法：未解決の質問、新規参加者、週次レポート
people · web	特定の人物について：プロフィール、各チャットでの発言、アカウントがボットらしいかどうか
bot · web	Bot API 経由のボット：トークン、受信者、メッセージ、管理者、すべての Bot API メソッド
replies · web	すべての人、または指定した人だけに、設定したルールに従ってメッセージに返信します
mcp · web	ターミナルを使わずに Claude Desktop、Cursor、その他のクライアントを接続する方法
remote · web	ログインプロキシとトンネルを介して、ブラウザー上の ChatGPT または Claude を利用します
recipes · web	エージェントが毎日できることと、スケジュールに従って実行する方法
compare · web	tg を tgcli、telegram-mcp、tdl と比較し、他のツールが適している場面を解説します
commands · web	すべてのコマンド、オプション、終了コード — プログラムから自動生成
configuration · web	よく使う動作の設定方法
permissions · web	プロフィールで読み取り可能な内容、事前確認が必要な操作、確認なしで実行できる操作
profiles · web	1台のコンピューターで複数のアカウントやボットを使う方法と、コマンドで使用するものの選択方法
configuration-reference · web	すべてのキー、型、デフォルト値、スコープ、変数
cli-contract · web	コマンドの実行、出力、エラー、ヘッドレス実行、制限、プレビュー
limits · web	制限、待機時間、バックグラウンドジョブ
diagnostics · web	コマンドの実行内容と、記録されることのない情報
troubleshooting · web	正常に動作しないとき：画面に表示される内容と対処方法
security · web	ディスクに保存される情報と保存されない情報、誤った宛先への送信を防ぐ仕組み
roadmap · web	今後の予定
各バージョンの変更内容：CHANGELOG.md。

開発

pnpm install
pnpm lint && pnpm typecheck && pnpm test
pnpm build && pnpm smoke:node # the built command, the bundle a user installs
pnpm build && pnpm smoke:bun  # the same under Bun
pnpm generate                 # rewrites docs/commands.md from the command tree
bin/tg session start          # everything under .tg/ in this checkout, never the real profile

Telegram 固有ではないもの、つまりコマンド、ストア、送信ガード、MCP サーバーはすべてmax-cliと共有されている cli-coreにあります。Telegram 固有のコードはsrc/telegram/だけにあります。

詳細：アーキテクチャ · テスト

貢献

プルリクエスト、バグ報告、アイデアを歓迎します。 issuesにお寄せください。

Telegram、その他のメッセンジャー、AI エージェントを使ったカスタム自動化について：[email protected]。

ライセンス

Apache License 2.0 — LICENSEをご覧ください。