unread

unread turns Telegram chats, YouTube videos, web pages, voice messages and files into short reports, with every claim linked back to the message, paragraph or timestamp it came from. It runs on your own machine or server, with whichever AI you have a key for: OpenAI, Anthropic, Google Gemini, OpenRouter or a local model.

Use it two ways:

• Command line: unread @somegroup --last-days 7 gives you a report on the week.
• Telegram bot: forward it a voice message, a PDF, a link or a YouTube video, and it replies with the summary.

Command line

curl -fsSL https://raw.githubusercontent.com/maxbolgarin/unread/main/scripts/install.sh | bash
unread init          # pick an AI provider and paste its key; Telegram is optional

unread @somegroup --last-days 7                  # a Telegram chat, channel or forum
unread "https://youtu.be/jmzoJCn8evU"            # a YouTube video
unread "https://paulgraham.com/greatwork.html"   # a web page
unread ./meeting.mp3                             # a file: audio, video, PDF, DOCX, image…
unread ask <any of the above> "your question"    # ask instead of summarize
unread dump <any of the above>                   # save the original text, no AI

Here is a real report: two weeks of @thehackernews, 99 messages, $0.016.

More: install options · sources · every command

Telegram bot

One command on a server (a small VM is plenty). It installs Docker if needed, asks a few questions and starts the bot:

curl -fsSL https://raw.githubusercontent.com/maxbolgarin/unread/main/scripts/install-bot-docker.sh | bash

You need a bot token from @BotFather, an AI key, and a Telegram API id + hash (free at my.telegram.org; the bot needs them to download files over 20 MB). You don't need to log in to your own Telegram account; do that later only if you want the bot to read t.me/… chat links too. Afterwards, unread-bot status | logs | update | config | users manages it, and /settings in the bot picks the AI model.

Already use the CLI? Skip Docker and run the bot from it; it becomes a systemd service where the machine has one:

unread bot setup && unread bot start

More: what the bot does · other ways to deploy it (Compose by hand, systemd, your own computer)

Highlights

• Citations on every claim. Each point links to its Telegram message, web paragraph or video timestamp.
• Any language in, any language out. A Russian chat can become an English digest.
• Voice and video. Voice messages, video notes, podcasts and recorded meetings are transcribed, then summarized.
• Your data stays yours. Everything is kept in SQLite under ~/.unread/, and keys can be encrypted at rest. Only your AI provider sees the text you analyze, and --redact strips phone numbers, emails and card numbers first.
• Cheap to run. Results are cached, long inputs are split and summarized in parallel, and --max-cost / --dry-run keep the bill in check.

AI providers

Provider	Notes
OpenAI	The default. Also transcribes voice and video.
Anthropic, Google Gemini	Analysis and images. Add an OpenAI key for voice and video.
OpenRouter	One key, many models.
Local (Ollama, LM Studio, vLLM)	Any OpenAI-compatible server; the AI runs on your own hardware.

Switch any time with unread settings, or /settings in the bot.

Documentation

Guide	What's in it
Install	Install options, first-run setup, where files live
Sources	Telegram, YouTube, web pages, files, presets, fact-checking
CLI reference	Every command and flag
Configuration	Languages, models, cost and caching, troubleshooting
Telegram bot	What it does, its commands and settings
Deploying the bot	Docker installer, Compose, systemd, Telegram session
Security	Threat model, encrypted secrets, PII redaction

The same guides are on the website.

Contributing

Pull requests are welcome. CONTRIBUTING.md covers the dev setup, lint and tests; report vulnerabilities as described in SECURITY.md. Issues and ideas: https://github.com/maxbolgarin/unread/issues.

Built on Telethon, yt-dlp, trafilatura, Typer, Rich and uv.

License

Apache 2.0, see LICENSE.