tg-hub

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