Reading List Bot

A Telegram bot that helps you manage your reading list with automatic metadata extraction and reading time estimates.

Setup

1. Supabase Setup

1. Go to supabase.com and create a free account
2. Create a new project
3. Go to the SQL Editor and run this to create the table:

CREATE TABLE reading_items (
    id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
    url TEXT NOT NULL,
    title TEXT,
    source TEXT,
    author TEXT,
    estimated_minutes INTEGER,
    word_count INTEGER,
    status TEXT DEFAULT 'unread',
    tags TEXT[],
    notes TEXT,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    read_at TIMESTAMPTZ,
    thumbnail_url TEXT
);

4. Go to Project Settings > API and copy:
   • Project URL (looks like https://xxxxx.supabase.co)
   • anon public key

2. Telegram Bot Setup

1. Open Telegram and message @BotFather
2. Send /newbot
3. Follow the prompts to name your bot
4. Copy the bot token

3. Environment Setup

cd reading-list-bot

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Create .env file from template
cp .env.example .env

Edit .env with your credentials:

TELEGRAM_BOT_TOKEN=your_token_here
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your_anon_key_here
WEEKLY_READING_BUDGET=300

4. Test Connection

python test_connection.py

5. Run the Bot

Quick run (stops when terminal closes):

python bot.py

Run persistently with tmux (recommended):

# Start a new tmux session
tmux new -s bot

# Inside tmux, run the bot
source venv/bin/activate
python bot.py

# Detach from tmux: press Ctrl+B, then D
# The bot keeps running in the background

tmux commands:

tmux attach -t bot    # Reattach to session
tmux ls               # List all sessions
tmux kill-session -t bot  # Stop the bot

Note: The bot stops when your computer sleeps or shuts down.

Usage

Once the bot is running, open Telegram and start a chat with your bot.

Commands

Command	Description
Send a URL	Saves the article with metadata
/list	Show your unread items (top 10)
/show <id>	Show full details for an item
/stats	View weekly reading progress
/random	Get a random item to read
/oldest	Get your oldest unread item
/done <id>	Mark an item as completed
/tag <id> <tags>	Add comma-separated tags
/modify <id> "New title"	Update an item's title
/search <keyword>	Search titles and URLs
/archive <id>	Archive an item
/remove <id>	Delete an item permanently
/save <url> [title]	Save a URL with an optional custom title
/help	Show help message

Example Workflow

1. See an interesting article on your phone? Share the URL to your bot
2. The bot extracts the title and estimates reading time
3. Later, run /list to see what's waiting
4. Use /random when you have time to read something
5. Run /done <id> when finished
6. Check /stats to see your weekly progress
7. Use /modify <id> "New title" or url | New title to fix titles

Reading Budget

The bot tracks your reading against a weekly budget (default: 300 minutes = 5 hours).

Change the budget in .env:

WEEKLY_READING_BUDGET=420  # 7 hours