Tg Hub

What it does

When your agent uses it

• Tasks that involve Statistics

Example prompts

• “Telegram”
• “tg-hub”
• “sync Telegram messages”
• “/tg-hub”

Requirements

• Python 3

Workflow steps

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

1. 1Use your own API credentials whenever possible: Go to https://my.telegram.org, create an application, and then set TG_API_ID / TG_API_HASH.
2. 2Control sync frequency: Avoid repeatedly running refresh() at high frequency.
3. 3Use delay and max_chats: For daily incremental refreshes, we recommend limiting the number of chats synced per round and keeping an…
4. 4Do not be too aggressive with the first full sync: tg-hub automatically applies a lower fetch limit for the first sync of each chat.
5. 5Prefer read operations: Local queries such as search and statistics do not use the network, so they are much lower risk than frequent syncs.

What it can do on your machine

Read from SKILL.md and the folder at commit ae8c5db. 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

  Ships 5 files in scripts/ (Python), which the agent can run.

  Shell commands in SKILL.md call:

  • uv

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • github.com

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Tg Hub loads about 2.3k tokens when it runs. Until then it costs about 199 tokens; SKILL.md has 659 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~199

When it runs · the whole SKILL.md, loaded when a task matches

~2.3k

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

• NoteMentions a .env fileSKILL.md:20

  environment variables directly, with no `.env` file required

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); the scripts in this folder are not scanned.

SKILL.md

The full file from OpenMinis/MinisSkills at commit ae8c5db, republished under its MIT licence (© OpenMinis). 659 words, ~2,286 tokens.

name

tg-hub

description

A skill for reading and writing Telegram data with Python and UV. It depends only on Telethon and uses a local-first architecture: messages are synced to SQLite and then queried offline. On first use, you must log in from the terminal with a phone number verification code. After that, the session is persisted and you do not need to log in again. Supports syncing group and channel messages locally, keyword search, multi-keyword filtering, today's messages, recent messages, speaker rankings, timeline statistics, and more. This skill must be triggered whenever the user mentions "Telegram", "TG", "Telegram", "tg-hub", "sync Telegram messages", "search TG groups", "Telegram keywords", "get TG messages", or any scenario that requires programmatically reading or writing Telegram data.

Telegram MTProto (telethon)
    ↓  sync / refresh (incremental)
Local SQLite  ~/.tg-hub/messages.db
    ↓  search / today / recent / filter (offline)
Structured data

/var/minis/skills/tg-hub/
├── SKILL.md
├── pyproject.toml          # telethon only
└── scripts/
    ├── __init__.py
    ├── config.py           # Configuration (environment variables / default paths)
    ├── db.py               # SQLite message storage
    ├── exceptions.py       # Structured exceptions
    └── client.py           # TGClient core class (all APIs)

1. Open Terminal
2. (Recommended) Set your own TG_API_ID / TG_API_HASH first
3. cd /var/minis/skills/tg-hub
4. uv run python -c "
   import sys; sys.path.insert(0,'.')
   from scripts.client import TGClient
   me = TGClient().login()
   print('Login successful:', me)
   "
5. Enter your phone number when prompted (in +86XXXXXXXXXX format)
6. Enter the verification code received in the Telegram app
7. After login succeeds, the session is saved automatically and future logins are not required

cd /var/minis/skills/tg-hub
uv sync

import sys
sys.path.insert(0, "/var/minis/skills/tg-hub")
from scripts.client import TGClient

client = TGClient()

# View the current account
me = client.whoami()
print(me["name"], me["phone"])

# List all conversations (fetched from TG in real time)
chats = client.list_chats()
for c in chats[:10]:
    print(f"  [{c['type']}] {c['name']}  Unread: {c['unread']}")

# Incrementally sync a single group
n = client.sync("Group name or username", limit=1000)
print(f"Added {n} messages")

# Quickly refresh all groups (up to 500 new messages per group)
# Slight throttling is enabled by default; you can also limit this round to only the first 30 chats
result = client.refresh(delay=1.0, max_chats=30)
for name, count in result.items():
    if count > 0:
        print(f"  {name}: +{count}")

# Search by keyword
msgs = client.search("Python", hours=48)
for m in msgs:
    print(f"[{m['chat_name']}] {m['sender_name']}: {m['content'][:80]}")

# Multi-keyword filtering (OR logic)
msgs = client.filter("hiring,remote,part-time", hours=24)

# Today's messages
msgs = client.today()

# Messages from the last 12 hours
msgs = client.recent(hours=12, limit=200)

# Speaker rankings
top = client.top_senders(hours=24)
for t in top[:5]:
    print(f"  {t['sender_name']}: {t['msg_count']} messages")

# Timeline statistics
tl = client.timeline(granularity="hour", hours=48)

# Local database statistics
stats = client.stats()
print(f"{stats['total']} local messages across {len(stats['chats'])} groups")

© OpenMinis, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 7 other files (scripts) in tg-hub of OpenMinis/MinisSkills.

• SKILL.md
• pyproject.toml
• scripts/__init__.py
• scripts/client.py
• scripts/config.py
• scripts/db.py
• scripts/exceptions.py
• uv.lock

Open the folder on GitHubat commit ae8c5db