Hacker News Bot

A Telegram bot that monitors Hacker News for trending articles, generates AI-powered summaries of the discussions, and delivers them straight to your Telegram chat.

Features

• RSS feed monitoring — fetches top stories from hnrss.org filtered by minimum points
• AI-powered summaries — uses OpenAI to distill HN comment threads into concise, structured articles
• Telegraph publishing — creates readable long-form pages on Telegraph
• Telegram notifications — sends formatted messages with links to the original article, HN discussion, and the generated summary
• Redis deduplication — tracks processed entries to avoid sending duplicate notifications
• Batch or service execution — process one feed batch for cron, or continuously poll for new entries
• Concurrent processing — handles multiple articles in parallel with configurable concurrency limits
• Retry with backoff — automatically retries transient HTTP failures

How It Works

hnrss.org RSS feed
        │
        ▼
  Filter by points
        │
        ▼
  Fetch HN comments ──► HTML → Markdown
        │
        ▼
  OpenAI summarisation
        │
        ▼
  Publish to Telegraph
        │
        ▼
  Notify via Telegram

Quick Start

Prerequisites

• Python 3.12+
• uv
• A Telegram Bot Token and a target chat ID
• An OpenAI API key
• A running Redis instance for local execution (included when using Docker Compose)

Install & Run

# Clone the repository
git clone https://github.com/narumiruna/hnbot.git
cd hnbot

# Install dependencies
uv sync

# Configure environment variables
cp .env.example .env
# Edit .env and fill in the required values

# Process one feed batch
uv run hnbot

# Or keep polling for new entries
uv run hnbot serve

hnbot and hnbot main process one feed batch and exit. hnbot serve immediately processes the current feed, then polls again after each completed batch. Redis prevents successfully processed entries from being sent again.

The service uses FEED_POLL_INTERVAL_SECONDS by default. Override it for one invocation with uv run hnbot serve --poll-interval 5; the interval must be at least one second.

Install from PyPI

pip install hnbot

Docker

Docker Compose is the recommended service setup. It builds hnbot, runs hnbot serve, and keeps Redis deduplication data in a named volume:

cp .env.example .env
# Edit .env and fill in the required values

docker compose up --build -d
docker compose logs -f hnbot

Stop the services without deleting Redis data:

docker compose down

To build or run the hnbot image without Compose, configure REDIS_HOST to a Redis server reachable from the container:

docker build -t hnbot .
docker run --env-file .env hnbot

# Run the image as a continuous service
docker run --env-file .env hnbot serve

Configuration

All settings are loaded from environment variables (or a .env file). See .env.example for the full template.

Required

Optional

Development

# Install all dependencies (including dev)
uv sync

# Run the full development gate (format → lint → type-check → test)
just all

# Or run individual steps
just format   # ruff format
just lint     # ruff check --fix
just type     # ty check
just test     # pytest with coverage

License

MIT