tg-hub

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.

tg-hub

Based on: jackwener/tg-cli (Apache-2.0)

This skill simplifies the original repository as follows:

• Removed the click / rich / python-dotenv / pyyaml dependencies
• Kept only telethon as a third-party dependency
• Removed the CLI layer and encapsulated all functionality as a synchronous Python API
• Changed the default session/db path to ~/.tg-hub/
• Changed configuration to read environment variables directly, with no .env file required

---

Architecture: Local-First

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

• Read operations (search/today/recent): query the local SQLite database, with no network access, and respond in milliseconds
• Write operations (sync/refresh): connect to Telegram to fetch new messages and write them incrementally to SQLite
• Session file: ~/.tg-hub/tg_hub.session

---

File Structure

~/.agents/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)

---

First-Time Login (Must Be Done in Terminal)

tg-hub uses the MTProto protocol (not the Bot API), so you need to log in with your Telegram account.

Recommendation: Use your own TG_API_ID / TG_API_HASH whenever possible. I have synced the upstream tg-cli anti-risk-control implementation: it uses a Telegram Desktop 5.x fingerprint and prints a warning if you continue using the default api_id=2040. The public app ID is only a fallback. Using your own credentials is still recommended for long-term use.

1. Open Terminal
2. (Recommended) Set your own TG_API_ID / TG_API_HASH first
3. cd ~/.agents/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

If you do not have your own credentials for now, you can log in with the built-in public credentials first. If you encounter login or fetch errors, switch to your own APP ID first.

Open a terminal and run:

cd ~/.agents/skills/tg-hub && uv run python -c "import sys; sys.path.insert(0,'.'); from scripts.client import TGClient; TGClient().login()"

---

Quick Start

Environment Setup

cd ~/.agents/skills/tg-hub
uv sync

Python Usage

import sys
sys.path.insert(0, "~/.agents/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[]}: ")


msgs = client.(, hours=)


msgs = client.today()


msgs = client.recent(hours=, limit=)


top = client.top_senders(hours=)
 t  top[:]:
    ()


tl = client.timeline(granularity=, hours=)


stats = client.stats()
()

---

API Quick Reference

Authentication

Method	Description
login()	Interactive login (first time, requires terminal)
whoami()	Get current account information

Sync (Online)

Method	Description
list_chats(chat_type=None)	List all conversations (real time)
sync(chat, limit=5000)	Sync a single group to local SQLite
sync_all(limit_per_chat=5000, delay=1.0, max_chats=None)	Sync all groups (with throttling/count limit)
refresh(limit_per_chat=500, delay=1.0, max_chats=None)	Quick incremental refresh (recommended for daily use)

Query (Local, Offline)

Method	Description
search(keyword, *, chat, sender, hours, regex, limit)	Keyword/regex search
filter(keywords, *, chat, hours)	Multi-keyword OR filtering
today(chat=None)	Today's messages
recent(hours=24, *, chat, sender, limit)	Messages from the last N hours
top_senders(chat, hours, limit)	Speaker rankings
timeline(chat, hours, granularity)	Timeline statistics
stats()	Database statistics
local_chats()	List of locally synced groups
delete_chat(chat)	Delete local messages for a group

---

Environment Variables

Variable	Default Value	Description
TG_API_ID	2040 (fallback only)	Recommended: replace with your own API ID
TG_API_HASH	Built in (fallback only)	Recommended: replace with your own API Hash
TG_SESSION_NAME	tg_hub	Session filename
TG_DATA_DIR	~/.tg-hub	Data directory
TG_DB_PATH	{TG_DATA_DIR}/messages.db	SQLite path
TG_DEVICE_MODEL	Desktop	Telethon client device model
TG_SYSTEM_VERSION	macOS 15.3	Telethon client system version
TG_APP_VERSION	5.12.1	Telethon client version
TG_LANG_CODE	en	Client language code
TG_SYSTEM_LANG_CODE	en-US	System language code

---

Account Security Recommendations

1. Use 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. Control sync frequency: Avoid repeatedly running refresh() at high frequency.
3. Use delay and max_chats: For daily incremental refreshes, we recommend limiting the number of chats synced per round and keeping an interval between chats.
4. Do 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. Prefer read operations: Local queries such as search and statistics do not use the network, so they are much lower risk than frequent syncs.

---

Notes

• The first login must be completed in an interactive terminal (a verification code is required).
• Using your own TG_API_ID / TG_API_HASH is strongly recommended to avoid risk-control issues caused by abuse of the public APP ID.
• tg-hub is aligned with the upstream tg-cli Telegram Desktop 5.x client fingerprint and retains environment variable overrides to reduce the risk of abnormal fingerprints.
• If you are still using the default api_id=2040, a warning is printed during connection to remind you to switch to your own TG_API_ID / TG_API_HASH.
• The session file is stored at ~/.tg-hub/tg_hub.session. Keep it safe.
• The first run of sync_all may take a long time, depending on the number of groups and the amount of historical messages.
• We recommend using refresh() for daily incremental updates and sync(chat, limit=10000) for the initial full sync.
• Telegram applies rate limits to API requests. During large syncs, Telethon automatically handles flood waits.