Telegram CLI client for AI agents
Connect your Telegram account to an agent, or use it from a terminal.
tg is a command-line tool that lets your AI agent read Telegram, find messages and help you reply. It works with your
personal account and its chats. You can also use it yourself with terminal commands.
It runs on Windows, macOS and Linux.
You are in the Telegram documentation. Use the messenger switch at the top to open MAX.
On this page
Choose how to start
Connect through your agent
If you use Codex, Claude Code, Cursor, Gemini CLI or Hermes, open the agent installation guide. Copy the short request: your agent will install the tool, help you log in and check the connection. You scan the QR code and confirm the login.
Then follow the guide for your agent. Apps that use an MCP server have a separate MCP guide.
Start in a terminal
Open the installation guide and choose the terminal instructions. After installing, run guided setup: it helps with app registration and login, checks your account and five chats, and installs agent skills. It reuses an existing session; downloading history remains a separate choice.
tg personal setuptg personal chats list --limit 5personal is the profile name: choose any name at the first login and repeat it in every command.
First, the command asks for your phone number and a code sent in Telegram to obtain api_id and api_hash from my.telegram.org. Then it displays the QR code for account login. Open Telegram on your phone → Settings → Devices → Link Desktop Device and scan it. Wait for Logged in as … before listing chats. Complete login steps.
What is a Telegram application and why is it needed?
This is a registration record for the program connecting to Telegram, here the tg CLI. You fill in a form, without writing or downloading another application. Telegram issues api_id and api_hash to identify the program; QR or code confirmation then grants access to your account. The command can register or retrieve these credentials for you. Explanation and browser fallback.
Try it after connecting
- Catch up on unread messages. Ask which chats are waiting for your reply.
- Recall agreements. Ask what you promised this week and what you are waiting for from others.
- Find a message. Ask for a conversation, date, link or file.
- Get help replying. Give your agent context and ask it to draft or send a message.
Reading does not mark messages as read. Sending, deleting and other changes require separate commands. You can restrict the agent's access: see access and safety.
Word search asks both the local archive and the messenger by default (--backend both); use --backend archive for local-only results. The query language is strict Lucene and does not correct typos; --discover also tries close spellings in the local archive. Prepare saved history before archive-only search, counting or rankings, and check coverage before treating an empty result as proof that a message is absent. See search.
Find the guide for your task
| Task | Guide |
|---|---|
| Read, search and send messages | Everyday commands |
| Log in, log out or add another account | Login and profiles |
| Search local history and export conversations | Message archive |
| Write a precise search query, filters or dates | Message search |
| Follow questions and membership in a group | Your groups |
| Find a ready request for your agent | Usage recipes |
| Check what Telegram bots currently support | Bots: available capabilities |
| Fix an error | Troubleshooting |
| Look up an exact command or option | Command reference |
| Manage contacts, aliases and private notes | People |
| Compare activity and inspect ranking evidence | Rankings |
| Send, download and read files | File commands |
| Transcribe voice messages locally | Voice commands |
| Configure optional model APIs | Model settings |
| Restrict reads, writes and confirmations | Permissions |
| Choose a personal or bot profile | Profiles and bots |
| Look up setting types and precedence | Configuration reference |
The left sidebar keeps Getting started and expandable Telegram/MAX guides available. The right sidebar lists sections of the current page. Use the command reference when you need an exact option; installation and everyday tasks are enough to get started.