snax-tg-bot

A personal Telegram assistant that syncs your messages and helps you triage, prioritize, and manage conversations — all from a single bot chat.

What it does

• Priority inbox — surfaces unread conversations ranked by urgency
• Follow-ups — park conversations you need to get back to later
• Contact tagging — tag contacts as Biz Dev, PizzaDAO, VIP, etc.
• Friends list — track when you last talked to people you care about
• Mute/dismiss — permanently or temporarily hide noisy chats
• AI drafts — get suggested replies powered by a local Ollama model
• Natural language — just type "1 and 3 are done" or "follow up on 5"
• Search — full-text search across all synced messages

Prerequisites

• Python 3.11+
• Ollama running locally with a model pulled (default: qwen2.5:14b)
• A Telegram API app (get credentials at https://my.telegram.org/apps)
• A Telegram bot (create one via @BotFather)

Setup

1. Clone and install

git clone https://github.com/snackman/snax-tg-bot.git
cd snax-tg-bot
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

2. Configure environment

cp .env.example .env

Edit .env with your values:

Variable	Where to get it
TG_API_ID	https://my.telegram.org/apps
TG_API_HASH	https://my.telegram.org/apps
TG_BOT_TOKEN	@BotFather on Telegram
SNAX_USER_ID	@userinfobot on Telegram

Optional variables (defaults are fine for most setups):

Variable	Default	Description
OLLAMA_MODEL	qwen2.5:14b	Ollama model for AI features
OLLAMA_HOST	http://localhost:11434	Ollama server URL
DB_PATH	data/messages.db	SQLite database location
INITIAL_SYNC_LIMIT	500	Messages to sync per chat on first run

3. Pull an Ollama model

ollama pull qwen2.5:14b

Or use a smaller model and update OLLAMA_MODEL in .env.

4. Run

python -m src.main

On first run, Telethon will prompt you to log in with your Telegram account (phone number + code). This creates a session file in data/ that persists across restarts.

Once running, open your bot in Telegram and send /help to see all commands.

Commands

Command	Description
/p	Show priority inbox
/done 1, 3	Dismiss items by number
/flup	View follow-up list
/flup 3, 5	Move items to follow-ups
/prio 1	Move back to priority
/fren	View friends list
/fren @user	Add a friend
/mute 2	Permanently ignore a user
/bd / /pd	View Biz Dev / PizzaDAO lists
/bd 3 / /pd @user	Tag contacts
/search <query>	Search messages
/reply @user <msg>	Send a message as you
/draft @user <topic>	AI-drafted reply
/note @user <text>	Add contact notes
/tier @user vip	Set priority tier

Numbers always refer to whichever list you last viewed — /p, /flup, /bd, or /pd.

Project structure

src/
  main.py          # Entry point — starts both clients
  bot_client.py    # Bot command handlers
  user_client.py   # Telegram user client for message sync
  database.py      # SQLite storage layer
  prioritizer.py   # Priority ranking logic
  llm.py           # Ollama integration
  query_engine.py  # Message search and context retrieval
  config.py        # Environment variable loading
data/              # Database and session files (gitignored)

License

MIT