Show HN: Unread – CLI that turns Telegram, YouTube and files into cited reports

A developer released Unread, a command-line tool that uses any LLM to turn Telegram chats, YouTube videos, web pages, and files into summarized reports with clickable citations. The tool aims to help users quickly digest large volumes of unread content by generating structured Markdown reports with source links.

Read your Telegram unread. Without reading it. A local CLI that turns Telegram chats, YouTube videos, web pages, and files into reports with citations — using whichever LLM you keep an API key for. You have 47 unread Telegram groups. You will never read them. You will now. curl -LsSf https://astral.sh/uv/install.sh | sh uv tool install unread && unread init unread @somegroup --last-days 7 It pulls the chat, runs it through whichever LLM you keep an API key for, and hands you a report with clickable citations back to every claim. Same shape for YouTube videos, web pages, voice messages, recorded meetings, podcasts, PDFs, and stdin. Or run it as a self-hosted Telegram bot and forward anything weird at it — see Self-hosted Telegram bot self-hosted-telegram-bot below. See a real report /maxbolgarin/unread/blob/main/.github/examples/summary.md from @thehackernews — 99 messages over two weeks, four chunks, $0.016, every bullet linked back to its source. Three verbs. The same <ref shape works on all of them. unread <ref — analyze . Map-reduce the source into a Markdown report. Every claim links back to its message / paragraph / timestamp. unread ask <ref "Q" — ask . One-shot Q&A with citations. Multi-turn follow-ups are one keystroke away. unread dump <ref — dump . Save the original — chat history, transcript, article — verbatim. No LLM call. <ref is any of: unread @somegroup --last-days 7 Telegram chat / channel / forum unread "https://youtu.be/jmzoJCn8evU" YouTube video captions or Whisper unread "https://paulgraham.com/greatwork" Web page / article unread ./meeting.mp3 Local file PDF, DOCX, audio, video, image cat notes.txt | unread Stdin This is the bit you actually want. Use unread tg to analyze any yours chats with interactive picker. Source language and report language are independent. The chat can be in Russian, the report in English. Or English source → Spanish report. Or anything → anything — the LLM does the heavy lifting and the source hint is optional. Russian-language group, English summary unread @forklog --last-days 7 --report-language en English channel, Russian summary unread @thehackernews --last-days 14 --report-language ru Out of the box, hand-tuned preset structures ship for en and ru under presets/<lang / .md /maxbolgarin/unread/blob/main/presets — section names, the forum addendum, the report skeleton. For any other report language the LLM writes the structure on the fly using the English preset as a template. It works. It's not as polished as the native trees. What you get back, for a Russian chat with --report-language en : Decisions - Migrate to indexed fund structures starting Q1 2026. 1586 https://t.me/c/3865481227/584/1586 - Drop the legacy K8s 1.27 cluster by end of month — Bob owns the rollout. 1604 ... Open questions - Who pays the OpenAI bill across the joint team? 1612 ... Every citation is a t.me link. Click → Telegram opens that message. unread handles forums topics , channel comments, voice notes transcribed , photos described , forwarded media deduped — Whisper runs once across N chats , and your folder structure --folder Work batches everything in that Telegram folder . The full source-shape matrix is in docs/sources.md /maxbolgarin/unread/blob/main/docs/sources.md . unread <youtube-url does the obvious thing: tries captions first, falls back to Whisper if the video has none. Every citation in the report becomes a t=SECONDS deep link, so clicking jumps you to that moment of the video. unread https://www.youtube.com/watch?v=Pmd6knanPKw unread https://www.youtube.com/watch?v=SBEtiXnLtpw --report-language de from what timecode should i start watching if i want to know about RAG? unread ask https://youtube.com/watch\?v\=k1njvbBmfsw "from what timecode should i start watching if i want to know about RAG?" unread dump https://www.youtube.com/watch?v=BDqvzFY72mg --mode=transcript Cached after the first run. Re-asking a question about the same video costs only the answer call — no yt-dlp, no Whisper, no re-spend. Plain web pages unread <url , PDFs, DOCX, Markdown, audio, video, and images all use the same <ref syntax. See docs/sources.md /maxbolgarin/unread/blob/main/docs/sources.md for the full list of supported extensions and the cache rules. That 12-minute voice message someone sent you. The 45-minute meeting recording you'll never play back. The hour-long lecture you wanted to skim. Drop any of them in and get a Markdown summary: unread ./meeting.mp3 audio → Whisper → summary unread ./standup.mp4 video → ffmpeg → Whisper → summary unread ./voice-note.ogg forwarded voice message saved to disk unread ./report.pdf PDF unread ./screenshot.png image vision Inside a Telegram chat the same step runs invisibly: voice notes and video circles are transcribed, photos are described, the analysis treats them as text. Forward a voice across five chats — Whisper runs once, cached by Telegram's stable document id . Whisper is roughly $0.006 per minute of audio. A 30-minute podcast costs under twenty cents. Re-running on the same file is free when it hits the cache. The full kind matrix and cache rules are in docs/sources.md media-enrichment /maxbolgarin/unread/blob/main/docs/sources.md media-enrichment . Drop in a key for any of these. Switch at any time with unread settings — caches and analyses persist across switches. | Provider | What you get | |---|---| OpenAI | Chat models + Whisper audio + embeddings + vision. The full toolkit. | Anthropic Claude | Chat models only. Pair with an OpenAI key if you also want voice / image enrichment. | Google Gemini | Chat models only. Same pairing note. | OpenRouter | One key, dozens of chat models — handy for trying Llama / DeepSeek / Mistral without separate signups. | Local Ollama / LM Studio / vLLM | OpenAI-compatible HTTP. Zero cost, zero data leakage, your own model. | Whisper / vision / embeddings are OpenAI-only. If you pick Anthropic or Google as your chat provider and also want media enrichment, add an OpenAI key alongside — unread init will offer it. 1. Install. uv handles the Python venv and binary. curl -LsSf https://astral.sh/uv/install.sh | sh macOS / Linux uv tool install unread 2. Interactive setup. Picks install folder, AI provider, Telegram optional . unread init 3. Run something. unread "https://paulgraham.com/greatwork.html" any web page unread ./meeting.mp3 any local file unread @somegroup --last-days 7 last week of a chat unread doctor confirm everything works unread help show help No virtualenv to activate, no pip conflicts, no global Python pollution. Upgrade later with uv tool upgrade unread . Skip the Telegram step if you only want YouTube / web / file analysis — those work with only an AI key. Full install matrix Windows / ffmpeg / dev install / editable is in docs/install.md /maxbolgarin/unread/blob/main/docs/install.md . Run the same pipeline as a Telegram bot. Forward it a voice message you don't feel like listening to, a PDF you don't feel like reading, a YouTube link, a t.me/... post from a channel you're not sure you want to subscribe to, or that suspicious link a friend just sent — you get a Markdown summary back as a document, with cost and timing in the caption. Single-user by design: the bot only answers ONE Telegram ID. The allowlist is auto-derived from the user session you give it mounted or sent via /upload session ; UNREAD BOT OWNER ID is only a bootstrap fallback for the case where no session is installed yet. Everyone else is silently dropped. Three install paths — pick by environment: 1. Local laptop / dev unread bot run foreground : uv tool install unread export UNREAD BOT TOKEN=123:abc... from @BotFather unread bot run 2. Fresh Linux VM — one line, blank disk to running systemd service: UNREAD EXECUTABLE="install-unread-bot.sh" && curl -fsSL https://raw.githubusercontent.com/maxbolgarin/unread/main/scripts/install-bot.sh $UNREAD EXECUTABLE && chmod +x $UNREAD EXECUTABLE && ./$UNREAD EXECUTABLE && rm ./$UNREAD EXECUTABLE Installs uv + ffmpeg + libpango, runs unread init , asks for the @BotFather token, drops a systemd --user unit that auto-restarts on crash and survives SSH disconnect. 3. Docker — pull the generic unread image from GHCR same image can also run one-off CLI commands; command: "unread","bot","run" in the compose file specifies the bot mode : cp .env.bot.example .env.bot && $EDITOR .env.bot docker compose -f docker-compose.bot.yml --env-file .env.bot up -d Reports default to PDF; set UNREAD BOT REPORT FORMAT=md in .env.bot to skip PDF rendering .md upload instead . The first time you message the bot with a t.me/... link it'll ask for /upload session — send your laptop's ~/.unread/storage/session.sqlite as a Telegram document and it's ready. Full feature reference slash commands, the confirm panel, what each input kind does is in docs/bot.md /maxbolgarin/unread/blob/main/docs/bot.md . End-to-end VM deployment guide covering all three paths is in . /maxbolgarin/unread/blob/main/docs/bot-vm-deploy.md docs/bot-vm-deploy.md I have ~50 Telegram groups I genuinely want to follow and not enough hours to read them. The same is true for the videos I bookmark and the articles I save to "read later." LLMs are now cheap enough that analyzing a week of group chat costs less than a coffee. My time is not. So I built the CLI I wanted to use — local-first, citation-backed, provider-agnostic — and now I open Telegram a lot less. Local-first. SQLite under ~/.unread/ . Your messages, embeddings, analyses, and secrets stay on your disk. The only network calls are to Telegram, your chosen AI provider, and any URLs you point at. Security. Your API keys, Telegram session, and other secrets can be encrypted at rest. You can use your OS keychain default or passphrase to unlock the CLI. Citations on every claim. Reports link back to the source message / paragraph / timestamp. --cite-context N expands citations into <details blocks with surrounding context, so the report is auditable without re-opening Telegram. Two-layer cache. Local analysis cache re-running an unchanged chat is free + the AI provider's prompt cache server-side discount on repeated prefixes . unread cache stats shows the hit rate. Cost guardrails. --max-cost 0.50 aborts or confirms before you spend more than that. --dry-run estimates without calling the model. unread stats shows lifetime spend by chat / preset / day. PII redaction. --redact scrubs phones, emails, IBANs, and Luhn-valid card numbers from what gets sent to the LLM. Originals stay in the local DB. Map-reduce, automatic. Big histories get chunked, summarized in parallel, then merged. Each chunk is cached independently — adding one message to the tail re-costs only the last chunk. Forums, channels with comments, folders. Telegram's awkward shapes are first-class. --all-per-topic , --with-comments , --folder Work . Encryption modes keystore , passphrase-derived pass , session hygiene, and the threat model are documented in docs/security.md /maxbolgarin/unread/blob/main/docs/security.md . Does this ship my Telegram history to OpenAI? Only the messages in the window you asked about, only after PII redaction if you set --redact , and only to the provider whose key you configured. Nothing else leaves the machine. The local cache is in your install dir; you can wipe it any time with unread cache ai purge . What if I don't use Telegram? Skip unread init 's Telegram step. unread <url and unread <file work with only an AI key. Most of the codebase is source-agnostic. What languages does it actually support? Source content: anything Whisper auto-detects audio or your LLM can read text — pretty much everything human languages cover. Reports: anything your LLM can write. EN and RU get hand-tuned preset structures; other report languages use the English preset as a template that the LLM translates on the fly. Will it cost me money? Yes — your AI provider charges. unread itself is free. Per-call USD is logged; --max-cost N caps a single run. Re-running an unchanged chat is free local cache hit . With cheap models gpt-5.4-mini -class, Gemini Flash, Claude Haiku the bill is small enough that most users stop reading the cost reports after a week. Is it actually fast? Fast enough that I stopped reading group chats. No benchmark table — speed depends on chat size, model choice, and your network. Try it with unread @somegroup --last-days 1 --dry-run to see the estimate before any LLM call. Can I run it on a server / in cron? Yes. Non-TTY mode skips interactive prompts. unread watch --interval 1h ... loops in the foreground run under tmux / systemd / nohup . API keys can come from env vars or ~/.unread/.env . The passphrase backend reads UNREAD PASSPHRASE for headless unlock. Can I plug in my own preset / prompt? --preset custom --prompt-file my-prompt.md . Same frontmatter format as the bundled ones in presets/ /maxbolgarin/unread/blob/main/presets . Bump prompt version in the frontmatter when you edit, otherwise the cache won't notice.The full reference manual lives under docs/ : | Topic | File | |---|---| | Install on macOS / Linux / Windows + first-run setup + where files live | docs/install.md | docs/sources.md watch , subscriptions docs/reference.md config.toml , maintenance, troubleshooting, architecture docs/configuration.md docs/security.md Useful inline help: unread --help , unread <subcommand --help , unread help , unread doctor . PRs welcome. Read CLAUDE.md /maxbolgarin/unread/blob/main/CLAUDE.md first — it's the contributor map DB invariants, cache keys, preset version bumps, the three language axes . covers the bench lint / format / tests . /maxbolgarin/unread/blob/main/CONTRIBUTING.md CONTRIBUTING.md for vulnerability reports. /maxbolgarin/unread/blob/main/SECURITY.md SECURITY.md uv sync --extra dev uv run pytest -q uv run ruff check . && uv run ruff format --check . Issues and feature requests: https://github.com/maxbolgarin/unread/issues https://github.com/maxbolgarin/unread/issues . Standing on the shoulders of: Telethon https://github.com/LonamiWebs/Telethon for the Telegram side, OpenAI Whisper https://platform.openai.com/docs/guides/speech-to-text / Anthropic https://www.anthropic.com/ / Google Gemini https://ai.google.dev/ / OpenRouter https://openrouter.ai/ / Ollama https://ollama.com/ for the LLM side, yt-dlp https://github.com/yt-dlp/yt-dlp for YouTube, trafilatura https://github.com/adbar/trafilatura for article extraction, tiktoken https://github.com/openai/tiktoken for token counting, Typer https://github.com/tiangolo/typer / Rich https://github.com/Textualize/rich / structlog https://www.structlog.org/ for the CLI shell, and uv https://github.com/astral-sh/uv for keeping all of the above out of your system Python. Apache 2.0 — see LICENSE /maxbolgarin/unread/blob/main/LICENSE .