telegram

telegram-agent

The universal Telegram agent-skill for Claude Code, Codex CLI, Cursor, Gemini CLI, Cline, Windsurf, OpenCode, and 40+ other AI coding agents. Lazy-loaded — ~0 context tokens until your prompt mentions Telegram. Standalone telegram-agent CLI plus the universal SKILL.md bundle, one-command install via npx skills.

Plugs your AI coding agent into a real Telegram user account via MTProto. The agent reads SKILL.md only when your prompt mentions Telegram — the rest of the time your context budget is untouched.

[!NOTE] telegram-agent v2+ is a fork of avemeva/kurier (GPL-3.0). The original CLI is agent-telegram; we rebranded, added Saved-Messages reaction-tags, portable session export/import, and the SKILL.md bundle for AI coding agents. See ATTRIBUTION.md for the full diff of what we added and changed.

v1.x (≤1.0.12) lived on gram.js under MIT — see the legacy-gramjs branch / tag v1.0.12.

Use it to: read dialogs · global message search · send / edit / forward / react · tag Saved Messages with reaction-tags (Premium) · moderate channels · send & download files · call raw MTProto methods. All against your real user account — no bot needed.

[!WARNING] This signs in as a real Telegram user (not a bot). Sessions live in ~/.telegram-agent/. Treat that directory like a password.

Why this exists

Most ways to wire an agent into Telegram load tool definitions into the model's context on every turn — costing tokens regardless of whether you ever say "Telegram" in the conversation. telegram-agent takes the opposite approach: the agent only sees a short skill description (~50 tokens) at boot. The full instructions (~250 tokens) are loaded only when your prompt matches — and even then they delegate execution to the telegram-agent CLI binary, not in-context tools.

	Context cost (idle)	Per-task cost
This package (skill + CLI)	0 tokens until matched	~250 tokens active

Supported clients: Claude Code · Codex CLI · Cursor · Gemini CLI · Cline · Windsurf · OpenCode · Continue · Roo · Goose · 40+ more via npx skills.

Prerequisites

• Node.js >=20
• Telegram API credentials from my.telegram.org/apps — api_id and api_hash

Install

One command. Drop the skill into your agent — it bootstraps the telegram-agent CLI, asks for your API credentials, and runs login itself on the first Telegram request.

npx skills add beautyfree/telegram-agent -a claude-code -g

That's it. The next time you say "check my Telegram", the agent will:

1. Run npm i -g telegram-agent if the binary isn't on $PATH.
2. Ask you once for TELEGRAM_API_ID / TELEGRAM_API_HASH from my.telegram.org/apps and persist them in your shell rc.
3. Run telegram-agent login — opens a local browser → phone → SMS code → 2FA. Session caches in ~/.telegram-agent/.

Prefer to do step 1–3 yourself, ahead of time? Run:

npm install -g telegram-agent
export TELEGRAM_API_ID=123456
export TELEGRAM_API_HASH=abc...
telegram-agent login

Picking the install method

Two ways to drop the skill in. Both end with the same SKILL.md in the right place on disk.

Option A — npx skills add (universal, 54+ agents) [recommended]

npx skills is the de-facto installer for the universal SKILL.md format. It supports 54 agent clients (claude-code, codex, cursor, gemini-cli, cline, windsurf, opencode, continue, roo, goose, aider-desk, kilo, warp, …).

npx skills add beautyfree/telegram-agent -a claude-code -g
npx skills add beautyfree/telegram-agent -a cursor -a codex -g
npx skills add beautyfree/telegram-agent                       # interactive picker

Flags worth knowing:

Flag	Purpose
-a, --agent <name>	Target a specific agent (repeatable). Run npx skills add beautyfree/telegram-agent --list to see the full agent list.
-g, --global	Install to $HOME/... instead of the current project.
-y, --yes	Skip confirmation prompts (CI-friendly).
--copy	Copy files instead of symlinking (symlink is the default — updates flow through).