Telegram Agent

telegram-agent

Put Telegram to work with your AI agent — without turning every conversation into a Telegram integration.

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.

Other installation options and supported clients

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.

[!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