telegram-agent

Telegram CLI for AI agents. Read messages, send messages, search, download media, manage chats — all from the terminal. JSON output, designed for automation.

Setup

Install the skill first with the interactive picker:

npx skills add beautyfree/telegram-agent -g

For CLI installation, sign-in, and troubleshooting, see the installation guide.

Authentication

telegram-agent connects to your real Telegram account — it reads and sends actual messages, not a sandbox. Authenticate before first use:

telegram-agent login                     # Log in to Telegram (interactive)
telegram-agent me                        # Verify connection

How It Works

A background daemon manages the TDLib connection and auto-starts on first command. TDLib caches your chats, messages, and user data locally, so most reads are instant (~0.2s) without hitting Telegram's servers. The daemon shuts down after 10 minutes of inactivity.

Quick Start

telegram-agent me                              # Current user info
telegram-agent chats list --limit 10           # Recent chats
telegram-agent msg list @username --limit 5    # Message history
telegram-agent action send @username "hello"   # Send a message
telegram-agent msg search "keyword"            # Search across all chats

Commands

Identity

telegram-agent me                                # Current user info
telegram-agent info <id|username|phone|link>     # Detailed entity info

Chats

telegram-agent chats list [--limit N] [--unread] [--type user|group|channel]
telegram-agent chats search "query" [--type chat|bot|group|channel] [--global]
telegram-agent chats members <chat> [--limit N] [--type bot|admin|recent]

Messages

telegram-agent msg list <chat> [--limit N] [--filter photo|video|document|voice]
telegram-agent msg get <chat> <msgId>
telegram-agent msg search "query" [--chat <id>] [--type private|group|channel]

Actions

telegram-agent action send <chat> "text" [--html] [--md] [--reply-to N] [--silent]
telegram-agent action edit <chat> <msgId> "text" [--html]
telegram-agent action delete <chat> <msgId...> [--revoke]
telegram-agent action forward <from> <to> <msgId...>
telegram-agent action pin <chat> <msgId>
telegram-agent action react <chat> <msgId> <emoji>
telegram-agent action click <chat> <msgId> <button>

Media

telegram-agent media download <chat> <msgId> [--output path]
telegram-agent media transcribe <chat> <msgId>

Real-time Streaming

telegram-agent listen --type user              # Stream events as NDJSON
telegram-agent listen --chat 12345             # Stream specific chat

Daemon

telegram-agent daemon start | stop | status | log

Auth

telegram-agent login                           # Log in to Telegram (interactive)
telegram-agent logout                          # Log out of Telegram

Advanced

telegram-agent eval --confirm '<javascript>'   # Run reviewed JS with connected TDLib client
telegram-agent doctor                          # Verify installation health

Entity Arguments

All commands accepting <chat> support:

• Numeric ID: 12345678, -1001234567890
• Username: @username or username
• Phone: +1234567890
• Link: t.me/username
• Special: me or self

Output

All output is JSON to stdout. Errors and warnings go to stderr. Pipe through jq for processing:

telegram-agent chats list --unread | jq '.data.items[].title'
telegram-agent msg search "meeting" | jq '.data.items[].content'

Pagination

List commands return hasMore and nextOffset. Pass the offset back to paginate:

telegram-agent msg list <chat> --limit 50
telegram-agent msg list <chat> --limit 50 --offset-id <nextOffset>

Claude Code Skill

Best suited for Claude Code. Install the skill to give Claude full Telegram access:

npx skills add beautyfree/telegram-agent

License

GPL-3.0