tg-hubA 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 sy…
Independent GitHub snapshot · Automated classification · Original documentation governs
Based on: jackwener/tg-cli (Apache-2.0)
This skill simplifies the original repository as follows:
- Removed the
click/rich/python-dotenv/pyyamldependencies- Kept only
telethonas a third-party dependency- Removed the CLI layer and encapsulated all functionality as a synchronous Python API
- Changed the default session/db path to
/var/minis/workspace/tg-hub/- Changed configuration to read environment variables directly, with no
.envfile required
Telegram MTProto (telethon)
↓ sync / refresh (incremental)
Local SQLite ~/.tg-hub/messages.db
↓ search / today / recent / filter (offline)
Structured data
~/.tg-hub/tg_hub.session/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)
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_HASHwhenever 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 defaultapi_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 /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
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 Terminal to log in
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")
| Method | Description |
|---|---|
login() | Interactive login (first time, requires terminal) |
whoami() | Get current account information |
| 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) |
| 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 |
| 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 |
https://my.telegram.org, create an application, and then set TG_API_ID / TG_API_HASH.refresh() at high frequency.delay and max_chats: For daily incremental refreshes, we recommend limiting the number of chats synced per round and keeping an interval between chats.TG_API_ID / TG_API_HASH is strongly recommended to avoid risk-control issues caused by abuse of the public APP ID.api_id=2040, a warning is printed during connection to remind you to switch to your own TG_API_ID / TG_API_HASH./var/minis/workspace/tg-hub/tg_hub.session. Keep it safe.sync_all may take a long time, depending on the number of groups and the amount of historical messages.refresh() for daily incremental updates and sync(chat, limit=10000) for the initial full sync.