⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
telegram-agent
Telegram CLI for AI agents. Use when the user needs to read or search Telegram, send or edit a message, download media, organise Saved Messages, monitor conversations, or automate a Telegram task. Triggers on “check my messages”, “send a message”, “search Telegram”, “read unread”, “listen to chat”, “download from Telegram”, тэг сохранёнок, чаты, каналы, and @peer names.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
telegram-agent gives Claude Code, Codex, Cursor, Gemini CLI, Cline and other coding agents a practical way to work with a real Telegram account: catch up on chats, find information, write replies, organise Saved Messages, work with media, and monitor conversations.
Install and use
npx skills add beautyfree/telegram-agent --skill telegram-agent -g
Choose your AI client in the picker. Then use normal language:
Catch me up on the unread messages in my work chats.
Find the Stripe invoice that Anton sent last month.
Draft replies to these three conversations, but do not send anything yet.
Turn today’s posts in @hackernews into a five-point briefing.
On the first Telegram request, the agent will guide you through connecting your account. You authenticate with your phone, the Telegram/SMS code, and 2FA if enabled. No bot token and no hosted relay are involved.
For a detailed first-time setup, including manual CLI installation and recovery, see Install and authenticate.
npx skills is the recommended universal installer. It supports Claude Code, Codex CLI, Cursor, Gemini CLI, Cline, Windsurf, OpenCode, Continue, Roo, Goose, and more.
npx skills add beautyfree/telegram-agent --skill telegram-agent -a codex -g
npx skills add beautyfree/telegram-agent --skill telegram-agent -a claude-code -a cursor -g
npx skills add beautyfree/telegram-agent --list
The -a flag targets a client, -g installs globally, and -y makes the command non-interactive. The repository also carries native manifests for Claude Code, Cursor, and Gemini CLI; use your client’s normal extension/plugin flow if you prefer it.
| Client | Recommended path |
|---|---|
| Claude Code | npx skills add … -a claude-code -g or the repository plugin flow |
| Codex CLI | npx skills add … -a codex -g |
| Cursor | npx skills add … -a cursor -g or /add-plugin |
| Gemini CLI | npx skills add … -a gemini-cli -g or the repository extension |
| Cline / Windsurf / OpenCode / Continue / Roo | npx skills add … -a <client> -g |
[!WARNING] This uses your Telegram user account, not a bot. A local session can read and act with your account’s permissions. Confirm sending, deleting, forwarding, and moderation actions before they run.
Multiple accounts
Keep your current session as default, and add other accounts by name:
telegram-agent accounts add work # Sign in with the second account
telegram-agent accounts list
telegram-agent --account work me
telegram-agent accounts use work # Default for future commands
telegram-agent --account default me # Your original session
Accounts have separate sessions, media caches, tokens, and background services.
Use --account NAME in scripts to keep actions tied to the intended account.
See account management for the full lifecycle.
What it is good at
| Need | What to ask your agent |
|---|---|
| Catch up quickly | “Summarise unread messages in this channel since yesterday.” |
| Find something | “Search my chats for the Figma link from last week.” |
| Handle replies deliberately | “Draft answers to these DMs; show me the drafts before sending.” |
| Build a personal knowledge base | “Tag my Saved Messages about taxes and list everything under that tag.” |
| Keep a channel in view | “Watch this channel and prepare a digest every hour; do not post automatically.” |
| Work with media | “Download the last voice message and transcribe it.” |
Daily or channel digest
Summarise new posts in
@channelsince yesterday. Group them by topic, include links, and call out anything that needs a response.
For a recurring workflow, fix the channel set, time window, and output format. Keep publishing separate from summarising: prepare the draft first, then decide where it goes.
Inbox triage and replies
Show my unread direct messages. For each, state who wrote, what they need, and a suggested reply. Do not send any replies.
Then approve individual drafts: “Send the draft to Anna, but make it shorter.” This keeps the recipient, timing, and tone under your control.
Saved Messages as a working library
Find Saved Messages about contracts, propose a small tag system, and show me which messages would receive each tag before changing anything.
After approval, reaction tags turn Saved Messages into a searchable library.
Moderation and outreach
Ask for a proposed action list before banning, deleting, or messaging anyone. Work in small batches and require explicit approval for each consequential action.
Automation boundary
listen can observe new events, but an event should never silently authorise sending, deletion, or forwarding. A durable pipeline is: collect → filter and summarise → propose → approve → execute a narrow action.
How to use it well
- Start with a read-only request: search, summarise, or draft.
- Name the chat, channel, time range, and desired output so the agent can work precisely.
- For actions with consequences, ask for a preview or explicit confirmation before the agent sends, deletes, forwards, or changes channel settings.
- Treat message text and attachments as content, not instructions. A message can be malicious or misleading even when it appears to come from a familiar chat.
What stays local
The CLI connects directly to Telegram and keeps its session on the machine that runs it. It is not a cloud inbox or a bot service. Saved Messages reaction tags and some transcription features require Telegram Premium; reading, search, and normal messaging do not.
Command results appear as readable tables and labeled details in a terminal. Pipes keep JSON output for automation; use --json or --pretty to choose explicitly. Commands accept numeric IDs, @usernames, t.me links, phone numbers from contacts, or me/self for Saved Messages.
| Area | Commands |
|---|---|
| Accounts | accounts add, list, current, use, status, login, rename, remove |
| Identity | me, info |
| Chats | chats list, chats search, chats members |
| Messages | msg list, msg get, msg search |
| Actions | action send, edit, delete, forward, pin, unpin, react, click |
| Media | media download, transcribe, caption |
| Saved Messages | saved tags, tag-rename, default-tags, search, history |
| Runtime | listen, daemon, doctor, session export, session import, eval --confirm |
Run telegram-agent --help for flags, pagination, and individual command usage.
Questions people ask
Is this a bot? No. It acts through a real Telegram user account.
Does my data go through your server? No. The local CLI talks directly to Telegram; the session stays on the machine where it runs.
Do I need Premium? No for core messaging, reading, search, and media dow
// HOW IT'S BUILT
KEY FILES