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 /var/minis/workspace/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

/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)

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 /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

Quick Start

Environment Setup

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

Python Usage

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")

API Quick Reference

Authentication

Sync (Online)

Query (Local, Offline)

Environment Variables

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 /var/minis/workspace/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.