Agent skill

Tlgr

Read and act on a personal Telegram account from the terminal with the tlgr CLI (MTProto user account, not a bot).

Install Tlgr

skills CLI

$ npx skills add tlgrcli/tlgr --skill tlgr -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install tlgrcli/tlgr tlgr --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/tlgrcli/tlgr.git skills-src && mkdir -p .claude/skills && cp -r skills-src/plugin/skills/tlgr .claude/skills/tlgr && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "tlgr" agent skill from https://github.com/tlgrcli/tlgr/tree/main/plugin/skills/tlgr into .claude/skills/tlgr/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tlgr", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/tlgrcli/tlgr/tree/main/plugin/skills/tlgr

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add tlgrcli/tlgr --skill tlgr -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install tlgrcli/tlgr tlgr --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/tlgrcli/tlgr.git skills-src && mkdir -p .agents/skills && cp -r skills-src/plugin/skills/tlgr .agents/skills/tlgr && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "tlgr" agent skill from https://github.com/tlgrcli/tlgr/tree/main/plugin/skills/tlgr into .agents/skills/tlgr/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tlgr", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add tlgrcli/tlgr --skill tlgr -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install tlgrcli/tlgr tlgr --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/tlgrcli/tlgr.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/plugin/skills/tlgr .cursor/skills/tlgr && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "tlgr" agent skill from https://github.com/tlgrcli/tlgr/tree/main/plugin/skills/tlgr into .cursor/skills/tlgr/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tlgr", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/tlgrcli/tlgr.git --path plugin/skills/tlgr

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add tlgrcli/tlgr --skill tlgr -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install tlgrcli/tlgr tlgr --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/tlgrcli/tlgr.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/plugin/skills/tlgr .gemini/skills/tlgr && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "tlgr" agent skill from https://github.com/tlgrcli/tlgr/tree/main/plugin/skills/tlgr into .gemini/skills/tlgr/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tlgr", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install tlgrcli/tlgr tlgr

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add tlgrcli/tlgr --skill tlgr -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/tlgrcli/tlgr.git skills-src && mkdir -p .github/skills && cp -r skills-src/plugin/skills/tlgr .github/skills/tlgr && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "tlgr" agent skill from https://github.com/tlgrcli/tlgr/tree/main/plugin/skills/tlgr into .github/skills/tlgr/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tlgr", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add tlgrcli/tlgr --skill tlgr -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install tlgrcli/tlgr tlgr --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/tlgrcli/tlgr.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/plugin/skills/tlgr .opencode/skills/tlgr && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "tlgr" agent skill from https://github.com/tlgrcli/tlgr/tree/main/plugin/skills/tlgr into .opencode/skills/tlgr/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "tlgr", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: tlgr
GitHub stars: 191
Token cost: ~1.5k tokens
SKILL.md length: 651 words
Files: 1
Skills in repo: 1
Repo updated: Oct 3, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Read and act on a personal Telegram account from the terminal with the tlgr CLI (MTProto user account, not a bot).

Works in 7 steps: Always pass --json. Errors are JSON on… → Reading can be visible. chat open sends… → Name the account when there is more than… → …
The user wants to check unread Telegram chats
SKILL.md covers Install and check, Rules that matter, Everyday loop and Beyond messages, plus 4 more sections
Calls pipx; needs TLGR_2FA_PASSWORD and TLGR_WEBHOOK_SECRET

What it does

Tlgr is an agent skill from tlgrcli/tlgr. Read and act on a personal Telegram account from the terminal with the tlgr CLI (MTProto user account, not a bot). Use when the user wants to check unread Telegram chats, read or search message history, send, reply to, edit, forward or schedule messages, manage chats, groups, channels, contacts, folders, reactions, polls, media or stories, or receive Telegram events through a webhook. Every command answers in JSON with stable exit codes.

Its SKILL.md is about 1.5k tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Backend & APIs, covering Webhooks. It works with Telegram and Python. The repository describes itself as: CLI for Telegram — agent-friendly, daemon-based, with webhook event push. The licence is MIT.

When your agent uses it

The user wants to check unread Telegram chats
Search message history
Schedule messages
Receive Telegram events through a webhook

Example prompts

“/tlgr”

Requirements

A credential in TLGR_WEBHOOK_SECRET

Workflow steps

7 steps, taken from the first numbered list in SKILL.md.

Always pass --json. Errors are JSON on stdout too, and the exit code
Reading can be visible. chat open sends a read receipt the other side
Name the account when there is more than one. Pass -a so a
Secrets never go in argv. Use --password-env, --api-hash-env,
Chats are @username or a numeric id. Display names and phone numbers
Preview before destructive calls with --dry-run, and confirm with the
Respect rate limits. Exit 7 carries wait_seconds; wait that long

What it can do on your machine

Read from SKILL.md and the folder at commit 647f171. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- pipx
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use pipx, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names these keys or tokens, usually read from environment variables:
- TLGR_2FA_PASSWORD
- TLGR_WEBHOOK_SECRET
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Tlgr loads about 1.5k tokens when it runs. Until then it costs about 112 tokens; SKILL.md has 651 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~112
When it runs · the whole SKILL.md, loaded when a task matches: ~1.5k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from tlgrcli/tlgr at commit 647f171, republished under its MIT licence (© tlgrcli). 651 words, ~1,541 tokens.

Download SKILL.mdSave it as .claude/skills/tlgr/SKILL.md (or your agent's skills folder).

name: tlgr
description: Read and act on a personal Telegram account from the terminal with the tlgr CLI (MTProto user account, not a bot). Use when the user wants to check unread Telegram chats, read or search message history, send, reply to, edit, forward or schedule messages, manage chats, groups, channels, contacts, folders, reactions, polls, media or stories, or receive Telegram events through a webhook. Every command answers in JSON with stable exit codes.

tlgr: Telegram for agents

tlgr controls a real Telegram user account over MTProto through a local daemon. Everything you can do in a Telegram app, you can do from a shell: messages, chats, groups, channels, contacts, media, stories, polls and more. The full reference is AGENT.md in the repository, and tlgr schema --json describes every command, flag and response.

Install and check

bash

pipx install tlgr-cli          # the command is `tlgr`
tlgr agent whoami --json       # active account, daemon health, schema version
tlgr status --check            # non-zero exit when anything is wrong

The daemon starts itself on first use. If whoami reports no account, go to Logging in.

Rules that matter

Always pass --json. Errors are JSON on stdout too, and the exit code is the contract. --results-only strips the envelope and --select a,b.c projects fields.
Reading can be visible. chat open sends a read receipt the other side sees and clears the owner's unread badge. To look without a trace use chat catchup, message list or chat open --no-read. A read receipt cannot be taken back; chat unread only restores the owner's badge.
Name the account when there is more than one. Pass -a <alias> so a message never goes out from the wrong identity.
Secrets never go in argv. Use --password-env, --api-hash-env, --token-env and friends, or their -stdin and -file forms.
Chats are @username or a numeric id. Display names and phone numbers are not accepted. Put negative ids after --: tlgr message list --json --limit 5 -- -100123456.
Preview before destructive calls with --dry-run, and confirm with the user before deleting, leaving, blocking or sending to someone new.
Respect rate limits. Exit 7 carries wait_seconds; wait that long before retrying. Exit 13 means the answer is unknown, never treat it as a "no".

Everyday loop

bash

tlgr catchup --json                                  # every unread chat with recent messages, no read receipts
tlgr message list @alice --json --limit 20           # silent history
tlgr message search @team "invoice" --json           # search one chat
tlgr message send @alice "On my way" --json          # send
tlgr message send @alice "Yes" --reply-to 4211 --json
tlgr message edit @alice 4212 "Yes, 5pm" --json
tlgr message forward @news 88 90 --to @archive --json
tlgr chat open @alice --json                          # history plus a visible read receipt

Long text over 4096 UTF-16 units is refused unless you add --split. --typing-auto shows "typing..." for a length-based duration before sending. --schedule TS schedules instead of sending now.

Lists return {items, has_more, next_cursor}. Pass --cursor <next_cursor> until has_more is false, or use --all.

Beyond messages

Each group has --help and a generated page in docs/reference/:

Group	Examples
`chat`	`list --unread`, `get --full`, `posters`, `members`, `archive`, `mute`, `leave`
`contact`, `user`, `resolve`	find, add and inspect people; turn a link or username into a peer
`reaction`, `poll`, `todo`, `location`	react, vote, create polls and checklists, share places
`media`, `sticker`, `gif`, `emoji`	upload, download, export
`story`, `folder`, `profile`, `privacy`	post stories, organise folders, change settings
`account`	`list`, `check`, `session list --unconfirmed`

Before planning something unusual, run tlgr agent capabilities --json. It separates what this build cannot do, what this account may not do (Premium, bot-only, admin-only) and what tlgr refuses on purpose, each with a reason.

Show full SKILL.md (225 more words)Show less

Logging in

bash

tlgr auth send-code +15551234567 --alias main --api-id 12345 --api-hash-env TLGR_API_HASH --json
tlgr auth verify-code 12345 --alias main --json

Ask the user for the code Telegram sends them. Exit 4 with AUTH_PASSWORD_REQUIRED means two-step verification is on: rerun verify-code with --password-env TLGR_2FA_PASSWORD after the user sets that variable. Never ask the user to paste a password into the chat.

Reacting to events

To be woken by Telegram instead of polling, the daemon can push events to an HTTP endpoint, signed with HMAC:

bash

tlgr webhook set --url https://example.com/hooks/agent \
  --events message_new,message_edited --secret-env TLGR_WEBHOOK_SECRET --enabled
tlgr webhook test

tlgr events list --json lists all event types. Deterministic auto-replies and forwards that need no model can run in the daemon as jobs in ~/.tlgr/jobs.yaml.

Limiting what you can do

--enable-commands message.list,message.send,chat.list (or TLGR_ENABLE_COMMANDS) allows only those operations; anything else exits 6. Use it when the user wants you read-only or restricted to a few actions. It is a guard rail, not a security boundary.

Exit codes

Code	Meaning	What to do
0	success	`meta.already: true` means it was already done
2	bad arguments	fix the call; check `tlgr schema <command> --json`
3	empty	nothing matched
4	auth needed	log in again
5	not found	wrong chat or id
6	permission denied or blocked by `--enable-commands`	do not retry
7	rate limited	wait `wait_seconds`
8	transient	retry shortly
11, 12	daemon or IPC problem	`tlgr daemon status --json`, then `tlgr daemon restart`
13	indeterminate	report as unknown

Files

Just SKILL.md in plugin/skills/tlgr of tlgrcli/tlgr.

Open the folder on GitHubat commit 647f171

Compare with similar skills

Tlgr next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Tlgr compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Tlgr this skilltlgrcli/tlgr	191	—	~1.5k	Automated safety check: Pass	MIT	4 days ago
Telegram Development Guide2025Emma/vibe-coding-cn	23k	1 repos	~3.7k	Automated safety check: Pass	MIT	9 mo ago
Telegramsickn33/agentic-awesome-skills	47k	2 repos	~411	Automated safety check: Pass	MIT	yesterday
X Twitter ScraperLeoYeAI/openclaw-master-skills	2.2k	—	~7.1k	Automated safety check: Pass	MIT	2 mo ago
Telegram Bot Builderaiskillstore/marketplace	430	3 repos	~2.2k	Automated safety check: Notes	None	today
Dingtalk Messageagentscope-ai/ReMe	3.6k	—	~1.6k	Automated safety check: Pass	Apache-2.0	yesterday

Similar skills

Telegram Development Guide
2025Emma/vibe-coding-cn
Chinese-language guide to building on Telegram: bots through the Bot API, Mini Apps in JavaScript and custom clients through TDLib, with Python examples.
23k GitHub starsUsed in 1 repo~3.7k tokens
Backend & APIsAuto-check passed
Telegram
sickn33/agentic-awesome-skills
Integracao completa com Telegram Bot API. An agent skill from sickn33/agentic-awesome-skills.
47k GitHub starsUsed in 2 repos~411 tokens
Backend & APIsAuto-check passed
X Twitter Scraper
LeoYeAI/openclaw-master-skills
X API & Twitter automation skill. An agent skill from LeoYeAI/openclaw-master-skills.
2.2k GitHub stars~7.1k tokensUpdated 2 mo ago
Backend & APIsAuto-check passed
Telegram Bot Builder
aiskillstore/marketplace
Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots.
430 GitHub starsUsed in 3 repos~2.2k tokens
Productivity & AutomationAuto-check: notes
Dingtalk Message
agentscope-ai/ReMe
钉钉消息发送技能。支持企业内部机器人（批量单聊/群聊）和 Webhook 自定义机器人两种接入方式，支持多机器人管理，支持文本、Markdown、链接、ActionCard、FeedCard等多种消息类型。
3.6k GitHub stars~1.6k tokensUpdated yesterday
Backend & APIsAuto-check passed
Stripe Best Practices
kanchengw/cnllm
Guides Stripe integration decisions — API selection (Checkout Sessions vs PaymentIntents), Connect platform setup (Accounts v2, controller properties), billing/subscriptions, Treasury financial…
175 GitHub starsUsed in 3 repos~925 tokens
Backend & APIsAuto-check passed

Works with

Questions about Tlgr

What does Tlgr do?

Read and act on a personal Telegram account from the terminal with the tlgr CLI (MTProto user account, not a bot). Tlgr is an agent skill from tlgrcli/tlgr. Read and act on a personal Telegram account from the terminal with the tlgr CLI (MTProto user account, not a bot).

When should I use Tlgr?

Tlgr fits situations like: the user wants to check unread Telegram chats; search message history; schedule messages; receive Telegram events through a webhook.

How do I install Tlgr in Claude Code?

Run `npx skills add tlgrcli/tlgr --skill tlgr -a claude-code`. Or copy the skill folder (plugin/skills/tlgr in tlgrcli/tlgr) into .claude/skills/tlgr in your project. Claude Code loads it when a task matches its description.

How do I install Tlgr in Codex?

Run `npx skills add tlgrcli/tlgr --skill tlgr -a codex`. Or copy the skill folder (plugin/skills/tlgr in tlgrcli/tlgr) into .agents/skills/tlgr in your project. Codex loads it when a task matches its description.

Can I use Tlgr in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add tlgrcli/tlgr --skill tlgr -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/tlgr, .gemini/skills/tlgr, .github/skills/tlgr and .opencode/skills/tlgr in your project.

What does Tlgr need to run?

Going by SKILL.md and its folder, Tlgr needs the command-line tools its instructions call (pipx) and credentials named TLGR_2FA_PASSWORD and TLGR_WEBHOOK_SECRET. Our summary lists: A credential in TLGR_WEBHOOK_SECRET.

Does Tlgr access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Tlgr safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Tlgr use?

Tlgr is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Tlgr use?

About 1.5k tokens (SKILL.md is roughly 6.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Tlgr?

Skills that share tags, products or a category with Tlgr: Telegram Development Guide (2025Emma/vibe-coding-cn, 23k stars), Telegram (sickn33/agentic-awesome-skills, 47k stars), X Twitter Scraper (LeoYeAI/openclaw-master-skills, 2.2k stars) and Telegram Bot Builder (aiskillstore/marketplace, 430 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Tlgr?

tlgrcli (a GitHub organization) maintains it in tlgrcli/tlgr, which has 191 GitHub stars. The repository was last updated on October 3, 2026.

Source: tlgrcli/tlgr on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Tlgr

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

tlgr: Telegram for agents

Install and check

Rules that matter

Everyday loop

Beyond messages

Logging in

Reacting to events

Limiting what you can do

Exit codes

Files

Compare with similar skills

Similar skills

Telegram Development Guide

Telegram

X Twitter Scraper

Telegram Bot Builder

Dingtalk Message

Stripe Best Practices

Related

Questions about Tlgr