{ "markdown": "

\n \"telegram-agent\"\n

\n

telegram-agent

\n

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

\n

\n \"npm\n \"skills.sh\n \"License\"\n \"Node\n

\n\n`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.\n\n## Install and use\n\n```bash\nnpx skills add beautyfree/telegram-agent --skill telegram-agent -g\n```\n\nChoose your AI client in the picker. Then use normal language:\n\n> Catch me up on the unread messages in my work chats.\n\n> Find the Stripe invoice that Anton sent last month.\n\n> Draft replies to these three conversations, but do not send anything yet.\n\n> Turn today’s posts in @hackernews into a five-point briefing.\n\nOn 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.\n\nFor a detailed first-time setup, including manual CLI installation and recovery, see [Install and authenticate](skills/telegram-agent/references/installation.md).\n\n
\nOther installation options and supported clients\n\n`npx skills` is the recommended universal installer. It supports Claude Code, Codex CLI, Cursor, Gemini CLI, Cline, Windsurf, OpenCode, Continue, Roo, Goose, and more.\n\n```bash\nnpx skills add beautyfree/telegram-agent --skill telegram-agent -a codex -g\nnpx skills add beautyfree/telegram-agent --skill telegram-agent -a claude-code -a cursor -g\nnpx skills add beautyfree/telegram-agent --list\n```\n\nThe `-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.\n\n| Client | Recommended path |\n| --- | --- |\n| Claude Code | `npx skills add … -a claude-code -g` or the repository plugin flow |\n| Codex CLI | `npx skills add … -a codex -g` |\n| Cursor | `npx skills add … -a cursor -g` or `/add-plugin` |\n| Gemini CLI | `npx skills add … -a gemini-cli -g` or the repository extension |\n| Cline / Windsurf / OpenCode / Continue / Roo | `npx skills add … -a <client> -g` |\n\n
\n\n> [!WARNING]\n> 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.\n\n## What it is good at\n\n| Need | What to ask your agent |\n| --- | --- |\n| Catch up quickly | “Summarise unread messages in this channel since yesterday.” |\n| Find something | “Search my chats for the Figma link from last week.” |\n| Handle replies deliberately | “Draft answers to these DMs; show me the drafts before sending.” |\n| Build a personal knowledge base | “Tag my Saved Messages about taxes and list everything under that tag.” |\n| Keep a channel in view | “Watch this channel and prepare a digest every hour; do not post automatically.” |\n| Work with media | “Download the last voice message and transcribe it.” |\n\n
\nWorkflow recipes\n\n### Daily or channel digest\n\n> Summarise new posts in `@channel` since yesterday. Group them by topic, include links, and call out anything that needs a response.\n\nFor 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.\n\n### Inbox triage and replies\n\n> Show my unread direct messages. For each, state who wrote, what they need, and a suggested reply. Do not send any replies.\n\nThen approve individual drafts: “Send the draft to Anna, but make it shorter.” This keeps the recipient, timing, and tone under your control.\n\n### Saved Messages as a working library\n\n> Find Saved Messages about contracts, propose a small tag system, and show me which messages would receive each tag before changing anything.\n\nAfter approval, reaction tags turn Saved Messages into a searchable library.\n\n### Moderation and outreach\n\nAsk for a proposed action list before banning, deleting, or messaging anyone. Work in small batches and require explicit approval for each consequential action.\n\n### Automation boundary\n\n`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.\n\n
\n\n## How to use it well\n\n- Start with a read-only request: search, summarise, or draft.\n- Name the chat, channel, time range, and desired output so the agent can work precisely.\n- For actions with consequences, ask for a preview or explicit confirmation before the agent sends, deletes, forwards, or changes channel settings.\n- 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.\n\n## What stays local\n\nThe 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.\n\n
\nCLI surface and data model\n\nAll CLI commands return JSON to stdout and accept numeric IDs, `@usernames`, `t.me` links, phone numbers from contacts, or `me`/`self` for Saved Messages.\n\n| Area | Commands |\n| --- | --- |\n| Identity | `me`, `info` |\n| Chats | `chats list`, `chats search`, `chats members` |\n| Messages | `msg list`, `msg get`, `msg search` |\n| Actions | `action send`, `edit`, `delete`, `forward`, `pin`, `unpin`, `react`, `click` |\n| Media | `media download`, `transcribe`, `caption` |\n| Saved Messages | `saved tags`, `tag-rename`, `default-tags`, `search`, `history` |\n| Runtime | `listen`, `daemon`, `doctor`, `session export`, `session import`, `eval --confirm` |\n\nRun `telegram-agent --help` for flags, pagination, and individual command usage.\n\n
\n\n## Questions people ask\n\n**Is this a bot?** No. It acts through a real Telegram user account.\n\n**Does my data go through your server?** No. The local CLI talks directly to Telegram; the session stays on the machine where it runs.\n\n**Do I need Premium?** No for core messaging, reading, search, and media downloads. Reaction tags in Saved Messages and some transcription capabilities are Premium features.\n\n**Can I use it in Docker or CI?** Yes, but that is advanced setup. Read [session portability and isolated state](skills/telegram-agent/references/installation.md#storage-and-controlled-portability) first.\n\n## Documentation\n\n- [Install, sign in, move a session, and troubleshoot](skills/telegram-agent/references/installation.md)\n- [CLI command reference](apps/cli/README.md)\n- [Security model and reporting](SECURITY.md)\n- [Technical details, compatibility, and upstream attribution](docs/technical-details.md) — including why [ATTRIBUTION.md](ATTRIBUTION.md) is retained for the GPL-3.0 fork\n- [Release history](CHANGELOG.md)\n", "bytes": 7876, "sha": "587360a9508b1211df1165d5f82c527e647b69c52f795e8afa6f99a6613257e1", "repo_slug": "beautyfree/telegram-agent", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_beautyfree_telegram_agent_088f2bf8/readme" }