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. Talks to Telegram directly through gram.js.

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:

Run npm i -g telegram-agent if the binary isn't on $PATH.
Ask you once for TELEGRAM_API_ID / TELEGRAM_API_HASH from my.telegram.org/apps and persist them in your shell rc.
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).

Option B — your agent's native command

Every supported agent has a native plugin/skill install command. Use it if you prefer the standard client UX or want the agent's own update flow. Click through for the exact incantation:

Claude Code

/plugin marketplace add beautyfree/telegram-agent
/plugin install telegram@telegram-agent
/reload-plugins

Drops the bundle under ~/.claude/plugins/cache/. Subsequent /plugin update pulls new versions.

Codex CLI

Inside Codex:

$skills
$telegram

Or drop the bundle manually with the universal installer:

npx skills add beautyfree/telegram-agent -a codex -g

Codex picks up ~/.agents/skills/telegram/ on the next session.

Cursor

In Cursor:

/add-plugin

Point it at this repo (beautyfree/telegram-agent). The repo already contains a .cursor-plugin/plugin.json so Cursor installs it as a native plugin with the skill bundle wired in.

Gemini CLI

gemini extensions install https://github.com/beautyfree/telegram-agent

Picks up gemini-extension.json from the repo and wires the skill into Gemini CLI.

Cline

npx skills add beautyfree/telegram-agent -a cline -g

Drops the bundle under ~/.clinerules/telegram/. Cline's rules engine reads it on every prompt and only follows the body when the description matches.

Windsurf

npx skills add beautyfree/telegram-agent -a windsurf

Project-scoped — run inside each project where you want Telegram available. Writes ./.windsurf/rules/telegram.md with trigger: model_decision.

Goose

Goose uses YAML recipes, not skill files. Wire telegram-agent (the binary) into a recipe's extensions: section if you want it inside a Goose flow.

3. Use it from any agent

Open Claude Code / Codex / Cursor / Gemini / Cline / Windsurf and just ask:

"summarize @hackernews from today" "tag my Saved Messages by topic" "send 'hello' to @friend" "find that link about Cloudflare Workers in my chats"

The agent reads SKILL.md, shells out to telegram-agent <command>, parses JSON, responds.

CLI surface

telegram-agent exposes the whole Telegram surface from one command. JSON to stdout — pipe through jq.

Group	Commands
Sessions	`login`, `logout`, `accounts`, `me`
Dialogs	`dialogs`, `search-dialogs`, `resolve`
Messages (read)	`messages`, `search`, `search-global`, `get`
Messages (write)	`send`, `edit`, `delete`, `forward`, `pin`, `unpin`, `react`, `mark-read`
Media	`send-file`, `download`
Saved Messages	`saved tags`, `saved tag-rename`, `saved search`, `saved dialogs`, `saved history`, `saved delete-history`, `saved toggle-pin`
Channels	`info`, `participants`
Raw MTProto	`invoke <Namespace.Class> --params '{...}'`

telegram-agent chats list --limit 10 | jq '.items[] | {title, unreadCount}'
telegram-agent msg search "stripe pricing" --limit 20
telegram-agent saved tags
telegram-agent action react me 12345 🧠         # tag a Saved Message
telegram-agent saved search --tag 🧠 --limit 50 # pull everything tagged "🧠"

Run telegram-agent help for the full flag reference.

How it works

Session — telegram-agent login opens a tiny local browser page for phone → SMS → 2FA, then stores the session at ~/.telegram-agent/.
Skill bundle — one SKILL.md (frontmatter name + description, ~250 tokens) with the full command list inline, plus narrow lazy-loaded references:
- references/installation.md — install, authentication, daemon storage, troubleshooting
- references/playbooks/saved-tags.md — categorize Saved Messages with reaction-tags
- references/playbooks/digest.md — batch summary of a channel or DM
- references/playbooks/moderation.md — bans, restrictions, admin-rights bitmasks
- references/playbooks/outreach.md — careful cold/warm DM campaigns with caps + cooldowns
The agent reads SKILL.md only when your prompt matches its description. References load on-demand inside that activation.
CLI — telegram-agent is a thin JSON-first wrapper around gram.js. A background daemon (auto-spawned on first use, idle-exits after 10 min) keeps the MTProto WebSocket warm so subsequent commands take ~200 ms instead of ~2 s.
Distribution — the repo follows the universal SKILL.md layout: skills/telegram/SKILL.md plus per-client marketplace manifests (.claude-plugin/marketplace.json, .claude-plugin/plugin.json, .cursor-plugin/plugin.json, gemini-extension.json). That's what makes both npx skills add beautyfree/telegram-agent and the agent-native commands work out of the box.

Compatibility matrix

Agent	Recommended install	Skill format	Install target
Claude Code	`npx skills add … -a claude-code -g` or `/plugin marketplace add`	Universal SKILL.md	`~/.claude/skills/telegram/`
Codex CLI	`npx skills add … -a codex -g`	Universal SKILL.md	`~/.agents/skills/telegram/`
Cursor	`/add-plugin` (or `npx skills add … -a cursor`)	Native plugin	`~/.cursor/plugins/local/telegram/`
Gemini CLI	`gemini extensions install …`	Extension	`~/.gemini/skills/telegram/`
Cline	`npx skills add … -a cline -g`	Rule pack	`~/.clinerules/telegram/`
Windsurf	`npx skills add … -a windsurf` (project)	Rule	`.windsurf/rules/telegram.md`
OpenCode / Continue / Roo / Warp / 40+ more	`npx skills add … -a <agent> -g`	Universal SKILL.md	agent-specific
Goose	wire `telegram-agent` into a YAML recipe	—	recipe `extensions:`

Environment

Variable	Required	Default	Notes
`TELEGRAM_API_ID`	yes	—	From my.telegram.org/apps. Prompted on first login if unset.
`TELEGRAM_API_HASH`	yes	—	Same as above.
`TELEGRAM_AGENT_HOME`	no	`~/.telegram-agent`	State + session storage.
`TELEGRAM_AGENT_DOWNLOADS`	no	`$TELEGRAM_AGENT_HOME/downloads`	Where `media download` saves files.
`LOG_LEVEL`	no	`info`	Set to `debug` for verbose stderr.

FAQ

Do I need Telegram Premium? No. Saved Messages reaction-tags are Premium-only; everything else works on a free account.

Bot or user account? User account. This is the MTProto API, not the Bot API. The agent acts as you. Treat your session like a password.

Why do I need npm i -g telegram-agent if I'm installing via npx skills? npx skills add only drops the SKILL.md instructions into your agent's skill directory. The skill instructs the agent to invoke telegram-agent from $PATH — so the binary still needs to be installed. A future revision may switch the skill to invoke via npx telegram-agent@latest to skip this step at the cost of cold-start latency on every call.

Is my data going somewhere? The session lives in ~/.telegram-agent/ on your machine. No third-party server. The CLI talks directly to Telegram's MTProto.

What about real-time push notifications? Use telegram-agent listen <chat> — subscribes to gram.js's NewMessage event and writes one JSON line per new message to stdout. Pipe it into while read line; do …; done for a tail-style loop.

Does it work with a Telegram Bot API token? No — this uses MTProto. For Bot API, you want a different package.

npx skills — universal SKILL.md installer (54+ agents).
Anthropic Skills docs — the universal SKILL.md format spec.
Codex Agent Skills — OpenAI's adoption of the same format.
Cursor Plugins — Cursor's native plugin system.
Gemini CLI Extensions — Google's extension manifest.
gram.js — the MTProto client under the hood.

Name		Name	Last commit message	Last commit date
Latest commit History 22 Commits
.claude-plugin		.claude-plugin
.cursor-plugin		.cursor-plugin
.github/workflows		.github/workflows
assets		assets
skills/telegram		skills/telegram
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
biome.json		biome.json
gemini-extension.json		gemini-extension.json
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

telegram-agent

Why this exists

Prerequisites

Install

Picking the install method

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

Option B — your agent's native command

3. Use it from any agent

CLI surface

How it works

Compatibility matrix

Environment

FAQ

Related

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

telegram-agent

Why this exists

Prerequisites

Install

Picking the install method

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

Option B — your agent's native command

3. Use it from any agent

CLI surface

How it works

Compatibility matrix

Environment

FAQ

Related

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

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

Packages