{"id":51090169,"url":"https://github.com/beautyfree/telegram-agent","last_synced_at":"2026-06-24T01:02:12.541Z","repository":{"id":358540010,"uuid":"1241786920","full_name":"beautyfree/telegram-agent","owner":"beautyfree","description":"Universal Telegram agent-skill for Claude Code, Codex CLI, Cursor, Gemini CLI, Cline, Windsurf. Lazy-loaded ~50x lower context vs MCP. Standalone CLI + SKILL.md bundle + one-command install.","archived":false,"fork":false,"pushed_at":"2026-06-14T01:37:51.000Z","size":1329,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T03:14:53.189Z","etag":null,"topics":["agent-skill","ai-agents","claude-code","cline","codex-cli","cursor","gemini-cli","gramjs","opencode","reaction-tags","saved-messages","skill-md","telegram","telegram-agent","telegram-api","telegram-cli","telegram-mtproto","telegram-skill","telegram-user","windsurf"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/beautyfree.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-17T20:16:10.000Z","updated_at":"2026-06-14T01:37:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/beautyfree/telegram-agent","commit_stats":null,"previous_names":["beautyfree/telegram-skill"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/beautyfree/telegram-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beautyfree%2Ftelegram-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beautyfree%2Ftelegram-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beautyfree%2Ftelegram-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beautyfree%2Ftelegram-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/beautyfree","download_url":"https://codeload.github.com/beautyfree/telegram-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/beautyfree%2Ftelegram-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34712578,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-skill","ai-agents","claude-code","cline","codex-cli","cursor","gemini-cli","gramjs","opencode","reaction-tags","saved-messages","skill-md","telegram","telegram-agent","telegram-api","telegram-cli","telegram-mtproto","telegram-skill","telegram-user","windsurf"],"created_at":"2026-06-24T01:02:03.517Z","updated_at":"2026-06-24T01:02:12.535Z","avatar_url":"https://github.com/beautyfree.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg width=\"20%\" src=\"assets/logo.png\" alt=\"telegram-agent\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003etelegram-agent\u003c/h1\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eThe universal Telegram agent-skill\u003c/b\u003e for Claude Code, Codex CLI, Cursor, Gemini CLI, Cline, Windsurf, OpenCode, and 40+ other AI coding agents. Lazy-loaded — \u003cb\u003e~0 context tokens\u003c/b\u003e until your prompt mentions Telegram. Standalone \u003ccode\u003etelegram-agent\u003c/code\u003e CLI plus the universal \u003ca href=\"https://code.claude.com/docs/en/skills\"\u003eSKILL.md\u003c/a\u003e bundle, one-command install via \u003ccode\u003enpx skills\u003c/code\u003e.\n\u003c/p\u003e\n\u003cdiv align=\"center\"\u003e\n\n[![npm version](https://badgen.net/npm/v/telegram-agent)](https://www.npmjs.com/package/telegram-agent)\n[![License](https://img.shields.io/npm/l/telegram-agent)](LICENSE)\n[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)\n\n\u003c/div\u003e\n\nPlugs your AI coding agent into a real Telegram user account via [MTProto](https://core.telegram.org/mtproto). The agent reads `SKILL.md` only when your prompt mentions Telegram — the rest of the time your context budget is untouched.\n\n\u003e [!NOTE]\n\u003e **`telegram-agent` v2+ is a fork of [avemeva/kurier](https://github.com/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`](./ATTRIBUTION.md) for the full diff of what we added and changed.\n\u003e\n\u003e v1.x (≤1.0.12) lived on [gram.js](https://github.com/gram-js/gramjs) under MIT — see the `legacy-gramjs` branch / tag `v1.0.12`.\n\n**Use it to:** read dialogs · global message search · send / edit / forward / react · tag Saved Messages with reaction-tags (Premium) · moderate channels · send \u0026 download files · call raw MTProto methods. All against your real user account — no bot needed.\n\n\u003e [!WARNING]\n\u003e This signs in as a real Telegram user (not a bot). Sessions live in `~/.telegram-agent/`. Treat that directory like a password.\n\n## Why this exists\n\nMost 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.\n\n| | Context cost (idle) | Per-task cost |\n| --- | --- | --- |\n| **This package** (skill + CLI) | **0 tokens** until matched | ~250 tokens active |\n\nSupported clients: Claude Code · Codex CLI · Cursor · Gemini CLI · Cline · Windsurf · OpenCode · Continue · Roo · Goose · 40+ more via [`npx skills`](https://github.com/vercel-labs/skills).\n\n## Prerequisites\n\n- Node.js `\u003e=20`\n- Telegram API credentials from [my.telegram.org/apps](https://my.telegram.org/apps) — `api_id` and `api_hash`\n\n## Install\n\nOne 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.\n\n```bash\nnpx skills add beautyfree/telegram-agent -a claude-code -g\n```\n\nThat's it. The next time you say \"check my Telegram\", the agent will:\n\n1. Run `npm i -g telegram-agent` if the binary isn't on `$PATH`.\n2. Ask you once for `TELEGRAM_API_ID` / `TELEGRAM_API_HASH` from [my.telegram.org/apps](https://my.telegram.org/apps) and persist them in your shell rc.\n3. Run `telegram-agent login` — opens a local browser → phone → SMS code → 2FA. Session caches in `~/.telegram-agent/`.\n\nPrefer to do step 1–3 yourself, ahead of time? Run:\n\n```bash\nnpm install -g telegram-agent\nexport TELEGRAM_API_ID=123456\nexport TELEGRAM_API_HASH=abc...\ntelegram-agent login\n```\n\n### Picking the install method\n\nTwo ways to drop the skill in. Both end with the same `SKILL.md` in the right place on disk.\n\n#### Option A — `npx skills add` (universal, 54+ agents) **[recommended]**\n\n[`npx skills`](https://github.com/vercel-labs/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`, …).\n\n```bash\nnpx skills add beautyfree/telegram-agent -a claude-code -g\nnpx skills add beautyfree/telegram-agent -a cursor -a codex -g\nnpx skills add beautyfree/telegram-agent                       # interactive picker\n```\n\nFlags worth knowing:\n\n| Flag | Purpose |\n| --- | --- |\n| `-a, --agent \u003cname\u003e` | Target a specific agent (repeatable). Run `npx skills add beautyfree/telegram-agent --list` to see the full agent list. |\n| `-g, --global` | Install to `$HOME/...` instead of the current project. |\n| `-y, --yes` | Skip confirmation prompts (CI-friendly). |\n| `--copy` | Copy files instead of symlinking (symlink is the default — updates flow through). |\n\n#### Option B — your agent's native command\n\nEvery 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:\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eClaude Code\u003c/b\u003e\u003c/summary\u003e\n\n```\n/plugin marketplace add beautyfree/telegram-agent\n/plugin install telegram@telegram-agent\n/reload-plugins\n```\n\nDrops the bundle under `~/.claude/plugins/cache/`. Subsequent `/plugin update` pulls new versions.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCodex CLI\u003c/b\u003e\u003c/summary\u003e\n\nInside Codex:\n\n```\n$skills\n$telegram\n```\n\nOr drop the bundle manually with the universal installer:\n\n```bash\nnpx skills add beautyfree/telegram-agent -a codex -g\n```\n\nCodex picks up `~/.agents/skills/telegram/` on the next session.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCursor\u003c/b\u003e\u003c/summary\u003e\n\nIn Cursor:\n\n```\n/add-plugin\n```\n\nPoint 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.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGemini CLI\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngemini extensions install https://github.com/beautyfree/telegram-agent\n```\n\nPicks up `gemini-extension.json` from the repo and wires the skill into Gemini CLI.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eCline\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nnpx skills add beautyfree/telegram-agent -a cline -g\n```\n\nDrops the bundle under `~/.clinerules/telegram/`. Cline's rules engine reads it on every prompt and only follows the body when the description matches.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eWindsurf\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nnpx skills add beautyfree/telegram-agent -a windsurf\n```\n\nProject-scoped — run inside each project where you want Telegram available. Writes `./.windsurf/rules/telegram.md` with `trigger: model_decision`.\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eGoose\u003c/b\u003e\u003c/summary\u003e\n\nGoose 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.\n\u003c/details\u003e\n\n### 3. Use it from any agent\n\nOpen Claude Code / Codex / Cursor / Gemini / Cline / Windsurf and just ask:\n\n\u003e *\"summarize @hackernews from today\"*\n\u003e *\"tag my Saved Messages by topic\"*\n\u003e *\"send 'hello' to @friend\"*\n\u003e *\"find that link about Cloudflare Workers in my chats\"*\n\nThe agent reads `SKILL.md`, shells out to `telegram-agent \u003ccommand\u003e`, parses JSON, responds.\n\n## CLI surface\n\n`telegram-agent` exposes the whole Telegram surface from one command. JSON to stdout — pipe through `jq`.\n\n| Group | Commands |\n| --- | --- |\n| **Sessions** | `login`, `logout`, `accounts`, `me` |\n| **Dialogs** | `dialogs`, `search-dialogs`, `resolve` |\n| **Messages (read)** | `messages`, `search`, `search-global`, `get` |\n| **Messages (write)** | `send`, `edit`, `delete`, `forward`, `pin`, `unpin`, `react`, `mark-read` |\n| **Media** | `send-file`, `download` |\n| **Saved Messages** | `saved tags`, `saved tag-rename`, `saved search`, `saved dialogs`, `saved history`, `saved delete-history`, `saved toggle-pin` |\n| **Channels** | `info`, `participants` |\n| **Raw MTProto** | `invoke \u003cNamespace.Class\u003e --params '{...}'` |\n\n```bash\ntelegram-agent chats list --limit 10 | jq '.items[] | {title, unreadCount}'\ntelegram-agent msg search \"stripe pricing\" --limit 20\ntelegram-agent saved tags\ntelegram-agent action react me 12345 🧠         # tag a Saved Message\ntelegram-agent saved search --tag 🧠 --limit 50 # pull everything tagged \"🧠\"\n```\n\nRun `telegram-agent help` for the full flag reference.\n\n## How it works\n\n1. **Session** — `telegram-agent login` opens a tiny local browser page for phone → SMS → 2FA, then stores the session at `~/.telegram-agent/`.\n\n2. **Skill bundle** — one `SKILL.md` (frontmatter `name` + `description`, ~250 tokens) with the full command list inline, plus narrow lazy-loaded references:\n   - `references/installation.md` — install, authentication, daemon storage, troubleshooting\n   - `references/playbooks/saved-tags.md` — categorize Saved Messages with reaction-tags\n   - `references/playbooks/digest.md` — batch summary of a channel or DM\n   - `references/playbooks/moderation.md` — bans, restrictions, admin-rights bitmasks\n   - `references/playbooks/outreach.md` — careful cold/warm DM campaigns with caps + cooldowns\n\n   The agent reads `SKILL.md` only when your prompt matches its description. References load on-demand inside that activation.\n\n3. **CLI** — `telegram-agent` is a thin JSON-first wrapper around [gram.js](https://github.com/gram-js/gramjs). 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.\n\n4. **Distribution** — the repo follows the [universal SKILL.md layout](https://code.claude.com/docs/en/skills): `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.\n\n## Compatibility matrix\n\n| Agent | Recommended install | Skill format | Install target |\n| --- | --- | --- | --- |\n| Claude Code | `npx skills add … -a claude-code -g` or `/plugin marketplace add` | Universal SKILL.md | `~/.claude/skills/telegram/` |\n| Codex CLI | `npx skills add … -a codex -g` | Universal SKILL.md | `~/.agents/skills/telegram/` |\n| Cursor | `/add-plugin` (or `npx skills add … -a cursor`) | Native plugin | `~/.cursor/plugins/local/telegram/` |\n| Gemini CLI | `gemini extensions install …` | Extension | `~/.gemini/skills/telegram/` |\n| Cline | `npx skills add … -a cline -g` | Rule pack | `~/.clinerules/telegram/` |\n| Windsurf | `npx skills add … -a windsurf` (project) | Rule | `.windsurf/rules/telegram.md` |\n| OpenCode / Continue / Roo / Warp / 40+ more | `npx skills add … -a \u003cagent\u003e -g` | Universal SKILL.md | agent-specific |\n| Goose | wire `telegram-agent` into a YAML recipe | — | recipe `extensions:` |\n\n## Environment\n\n| Variable | Required | Default | Notes |\n| --- | --- | --- | --- |\n| `TELEGRAM_API_ID` | yes | — | From my.telegram.org/apps. Prompted on first login if unset. |\n| `TELEGRAM_API_HASH` | yes | — | Same as above. |\n| `TELEGRAM_AGENT_HOME` | no | `~/.telegram-agent` | State + session storage. |\n| `TELEGRAM_AGENT_DOWNLOADS` | no | `$TELEGRAM_AGENT_HOME/downloads` | Where `media download` saves files. |\n| `LOG_LEVEL` | no | `info` | Set to `debug` for verbose stderr. |\n\n## FAQ\n\n**Do I need Telegram Premium?**\nNo. Saved Messages reaction-tags are Premium-only; everything else works on a free account.\n\n**Bot or user account?**\nUser account. This is the MTProto API, not the Bot API. The agent acts as you. Treat your session like a password.\n\n**Why do I need `npm i -g telegram-agent` if I'm installing via `npx skills`?**\n`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.\n\n**Is my data going somewhere?**\nThe session lives in `~/.telegram-agent/` on your machine. No third-party server. The CLI talks directly to Telegram's MTProto.\n\n**What about real-time push notifications?**\nUse `telegram-agent listen \u003cchat\u003e` — 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.\n\n**Does it work with a Telegram Bot API token?**\nNo — this uses MTProto. For Bot API, you want a different package.\n\n## Related\n\n- [`npx skills`](https://github.com/vercel-labs/skills) — universal SKILL.md installer (54+ agents).\n- [Anthropic Skills docs](https://code.claude.com/docs/en/skills) — the universal SKILL.md format spec.\n- [Codex Agent Skills](https://developers.openai.com/codex/skills) — OpenAI's adoption of the same format.\n- [Cursor Plugins](https://cursor.com/docs/plugins) — Cursor's native plugin system.\n- [Gemini CLI Extensions](https://geminicli.com/docs/extensions/) — Google's extension manifest.\n- [gram.js](https://github.com/gram-js/gramjs) — the MTProto client under the hood.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeautyfree%2Ftelegram-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbeautyfree%2Ftelegram-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbeautyfree%2Ftelegram-agent/lists"}