══════════════════════════
R S S D I G E S T
══════════════════════════
Generates a digest from your self-hosted RSS reader using your choice of LLM. Instead of scrolling through hundreds of unread articles, you get a single readable summary grouped by theme — delivered as a Markdown or HTML file.
What you need
- A self-hosted RSS reader that supports the GReader API (FreshRSS, Miniflux, etc.)
- An API key for an AI service (Anthropic, OpenAI, or a local model — see Choosing a model)
- uv or pipx for installation
Installation
# with uv
uv tool install rss-digest
# with pipx
pipx install rss-digest
Quick start
# Set your secrets
export GREADER_PASSWORD=yourpassword
export ANTHROPIC_API_KEY=sk-ant-...
# Generate a digest of the last 24 hours
rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname
The digest is written to digest-YYYY-MM-DD.md in the current directory. Pass --html to get an HTML file instead.
Configuration
Settings are passed on the command line, grouped by the service they configure. Only secrets come from the environment: the GReader password from GREADER_PASSWORD, and your LLM provider's API key from its own variable (see Choosing a model).
Instead of exporting them, you can put the secrets in a .env file in the directory you run rss-digest from. Variables already set in the environment take precedence over the file.
# .env
GREADER_PASSWORD=yourpassword
ANTHROPIC_API_KEY=sk-ant-...
Feed reader (GReader API)
| Option | Default |
|---|---|
--greader-url URL |
(required) the reader's GReader API endpoint (see Compatible readers) |
--greader-username USER |
(required) |
--mark-read |
off |
LLM
| Option | Default |
|---|---|
--model MODEL |
anthropic/claude-sonnet-5 |
--model-url URL |
the provider's endpoint |
--prompt-file FILE |
built-in prompt |
--print-prompt |
off (print the prompt and exit) |
Digest
| Option | Default |
|---|---|
--hours N |
24 |
--archive-dir DIR |
off (no history) |
--history N |
3 |
--summary-length N |
1000 (how much of each article is sent) |
--html |
off |
--output PATH |
./digest-YYYY-MM-DD.md |
--quiet |
off |
--verbose |
off |
--log-file FILE |
off |
The examples below leave out --greader-url and --greader-username to keep them short; every real run needs both.
# Last 48 hours, HTML output
rss-digest --hours 48 --html
# Use a different model
rss-digest --model openai/gpt-4o
How much of each article is sent
Each article reaches the LLM as its title, link, feed name and the first
--summary-length characters of the text the feed published (default 1000).
That's what the digest has to work with: from a headline and a one-line lede the
model can only restyle the headline, while a few paragraphs let it say what the
piece actually argues or reports.
How much text there is depends on the feed. Many blogs and long-form publications
put the whole article in the feed; news sites often send a teaser of a sentence
or two, and some send nothing at all. --verbose prints, for each feed, how many
articles came in and the median and longest text length, thinnest feeds first:
Summary length per feed (characters, before --summary-length):
feed n median max
Hugging Face - Blog 3 0 0
NYT > Technology 9 263 404
3 Quarks Daily 12 1130 7320
ProPublica 2 11715 14533
A longer --summary-length only helps feeds that have the text. It costs prompt
tokens in proportion: about 150 articles at 2000 characters is roughly
60k tokens. A busy reader with many hundreds of articles a day may need a lower
setting to stay inside the model's context window; --summary-length 0 sends
titles only.
Link roundups
Posts that are mostly a list of other people's links (Hacker News Daily, newsletters, links blogs) are sent differently. Reduced to text, such a post is a run of headlines with no URLs, so the model could neither link nor weigh them. Instead each recommended link is sent as an item of its own, under a heading that names the roundup, and the model is asked to file them by theme alongside everything else and credit the roundup in passing ("via Hacker News Daily").
A post counts as a roundup when most of its text is link text and the links open
their list items or headings, as headlines do. Essays that cite heavily, and posts
with a link in each paragraph, are left as they are. Links back to the roundup's
own site, front-page links and "(comments)"-style links are skipped. With
--print-prompt you can see which posts were split.
Continuity between digests
Point --archive-dir at a folder of past digests and they're sent along with the
new articles, inside a <previous_digests> block, so the LLM can follow up on
ongoing stories and avoid re-telling one it already covered — feeds echo each
other, and the same story often arrives from three sources over two days.
# Keep the digests you've read in one folder, then feed them back
rss-digest --archive-dir ~/Documents/rss-digests
Nothing is ever written to --archive-dir. You file digests there yourself,
which is the point: the folder holds only what you actually read, so that's what
shapes the next digest.
Any .md or .html file in the folder counts, whatever it's named — so however
you set --output, it works. HTML is converted back to markdown, and the
generated header, stats line and footer are stripped. Each digest is dated by the
date in its filename if there is one, otherwise by when the file was created;
anything dated today is skipped, so running twice in one day won't feed a digest
to itself.
Without --archive-dir there's no history and nothing changes. --history N
tunes how many digests to send (default 3) and requires --archive-dir.
There is no separate "context" parameter in a chat completion — the block is just
text prepended to the user message. Measured on a 151-article day with
count_tokens, at an earlier 300-character summary length: 25.5k tokens for the articles and ~3k per digest of history, so
--history 3 puts the whole prompt near 35k. History is a real third of the
prompt at that setting, but a fraction of a cent per run — nothing worth
compressing.
The trade-off worth watching is anchoring: given yesterday's digest, a model will
happily reproduce yesterday's section headings and manufacture continuity where
there is none. The system prompt guards against this explicitly, and that guidance
is appended to your own prompt too when you use --prompt-file, so custom
prompts don't lose it. If a digest still reads like the previous day's, compare
against a run with --archive-dir left off.
Choosing a model
rss-digest uses LiteLLM, so any model it supports works. Set the --model flag to a LiteLLM model string and export the corresponding API key. To use an OpenAI-compatible API or a LiteLLM gateway, point --model-url at it.
Anthropic (default)
export ANTHROPIC_API_KEY=sk-ant-...
rss-digest --model anthropic/claude-sonnet-5
OpenAI
export OPENAI_API_KEY=sk-...
rss-digest --model openai/gpt-4o
Local model via LM Studio
LM Studio lets you run models on your own machine with no API key or usage costs.
- Download and open LM Studio, load a model (Mistral, Llama, Gemma, etc.)
- Start the local server: Local Server tab → Start Server
- Copy the [model identifier] shown in the UI (e.g.
google/gemma-4-12b-qat) - Invoke
rss-digestwith the--modelparameter, but prefixing the model identifier withopenai/, e.g.openai/google/gemma-4-12b-qat.
export OPENAI_API_KEY=lm-studio
rss-digest --model-url http://localhost:1234/v1 --model openai/google/gemma-4-12b-qat
The OPENAI_API_KEY value is ignored by LM Studio but required by the LiteLLM library — set it to anything. The model name after openai/ must match the identifier shown in LM Studio's server tab.
LiteLLM gateway or other OpenAI-compatible API
Hosted gateways built on LiteLLM, such as Inference Coop, let you use many models through one account. Prefix the gateway's model name with litellm_proxy/ and put your gateway key in LITELLM_PROXY_API_KEY:
export LITELLM_PROXY_API_KEY=sk-...
rss-digest --model-url https://gateway.inference.coop --model litellm_proxy/MODEL_NAME
To list the model names the gateway offers:
curl -H "Authorization: Bearer $LITELLM_PROXY_API_KEY" https://gateway.inference.coop/v1/models
For any other OpenAI-compatible API, use the openai/ prefix and OPENAI_API_KEY instead, as in the LM Studio example above.
For digest-length tasks, a 7B–14B instruction-tuned model works well. Larger context windows (32k+) are helpful if you have many unread articles.
Customizing the prompt
The built-in prompt decides how articles are grouped and how much to include. For ≤25 articles it lists everything; for larger batches it writes a curated prose summary.
You are producing a digest of RSS articles.
Format rules:
- ≤25 articles: Reading queue. Group by theme under ### headings. List every
article as a bullet with a markdown link. Include the feed name.
- >25 articles: Curated TL;DR. Themed prose under ### headings. Cover roughly
⅓ of articles. Drop filler (sponsored posts, job listings, police blotters,
sub-100-word link-outs). Dense single-feed clusters (6+ posts): pick 2–3
representatives, then "and N more from [feed name]".
Every article title you mention must be an inline markdown link. Be concise.
To use your own prompt, write it to a text file and pass it with --prompt-file:
rss-digest --prompt-file my-prompt.txt
Example prompt that keeps things very short:
You are summarizing RSS articles for a busy reader.
Write a single short paragraph (5–8 sentences) covering the most important stories.
Do not use bullet points or headings. Every article title must be a markdown link.
The user message sent to the model is always a structured list of articles grouped by feed, so your prompt only needs to describe the desired output format.
Inspecting the prompt
To see the exact system prompt and user message that would be sent to the model — without making any LLM call — use --print-prompt:
rss-digest --print-prompt
This is useful for iterating on a custom prompt, checking which articles were fetched, or piping the content to another tool.
Example output
See example.md for a real digest. A short excerpt:
# RSS Digest — 2026-06-10
*137 articles · 53 sites*
### Science & Environment
NASA [announced the all-male Artemis III crew](https://www.nytimes.com/2026/06/09/science/space/artemis-iii-astronauts-nasa-crew.html) and faces questions about [whether a 2028 moon landing is realistic](https://www.nytimes.com/2026/06/09/science/space/nasa-artemis-moon-landing.html) given dependence on Musk and Bezos. Indonesia's landslides [wiped out over 5% of the endangered orangutan population](https://www.nytimes.com/2026/06/10/climate/indonesia-floods-organgutans.html). And scientists [accidentally found that crowds worldwide spontaneously walk counterclockwise](https://www.404media.co/scientists-just-accidentally-discovered-a-strange-hidden-rule-of-human-nature/).
### Culture & Ideas
3 Quarks Daily examines [what AGI means for the future of physics](https://3quarksdaily.com/3quarksdaily/2026/06/adam-brown-agi-the-future-of-physics.html), and Dina Nayeri writes on [Iran's stolen revolution and the failures of diaspora narrative](https://3quarksdaily.com/3quarksdaily/2026/06/stolen-revolution.html). Iron & Wine's Sam Beam [reflects on always developing and changing as an artist](https://thecreativeindependent.com/people/musician-sam-beam-iron-and-wine-on-always-developing-and-changing/). A fascinating science/humanities crossover: [ELIZA and what a 1966 chatbot's horrified inventor tells us about modern voice AI](https://cafebedouin.org/2026/06/10/eliza-learned-to-breathe/).
Running on a schedule
To get a fresh digest every morning, add a crontab entry. Cron runs jobs with a minimal environment, starting in your home directory, so use the full path to the binary and give it its secrets explicitly.
# find the full path first
which rss-digest
The simplest way to supply the secrets is a .env file (see Configuration) in a directory of your choice, which the job cds into first. Open your crontab with crontab -e and add:
# Run at 6am every day, write an HTML digest to a specific folder
0 6 * * * cd /Users/yourname/rss-digest && /Users/yourname/.local/bin/rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname --html --quiet --log-file /tmp/rss-digest.log --output /Users/yourname/Documents/digest.html
Alternatively, set the secrets in the crontab itself. Crontab env-var lines apply to every job below them in the file, including unrelated ones, which is one reason to prefer .env:
GREADER_PASSWORD=yourpassword
ANTHROPIC_API_KEY=sk-ant-...
0 6 * * * /Users/yourname/.local/bin/rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname --html --quiet --log-file /tmp/rss-digest.log --output /Users/yourname/Documents/digest.html
Using digests you've read as context
Write each morning's digest somewhere you'll see it, and file the ones you read
into a folder you pass as --archive-dir. Continuity then reflects only what you
actually read, and the job never writes into the folder you curate by hand:
0 6 * * * cd /Users/yourname/rss-digest && /Users/yourname/.local/bin/rss-digest --greader-url https://freshrss.example.com/api/greader.php --greader-username yourname --html --quiet --archive-dir /Users/yourname/Documents/rss-digests --output /Users/yourname/Desktop/`date +\%Y-\%m-\%d`.html
Development
uv sync # install, including dev dependencies
uv run pytest # tests
uv run ty check # type checking
uv run ruff format # formatting
CI runs all three on Python 3.12 and 3.13 for every push to main and every
pull request, with ruff format --check so unformatted code fails the build.
ty and ruff are unpinned in pyproject.toml, but CI installs from uv.lock,
so the version only moves when you run uv lock — both are pre-1.0, and a new
release can add checks or change formatting, so it's better to see that as a
diff than as a surprise red build.
This project was bulk-reformatted once. To keep that commit out of git blame:
git config blame.ignoreRevsFile .git-blame-ignore-revs
Compatible readers
Any RSS reader that implements the GReader API should work:
| Reader | --greader-url |
Notes |
|---|---|---|
| FreshRSS | https://freshrss.example.com/api/greader.php |
Enable the GReader API in Settings → Authentication |
| Miniflux | https://miniflux.example.com |
Enable Google Reader API in Settings |
| Tiny Tiny RSS | see the plugin's documentation | Requires the News+/GReader plugin |
| The Old Reader | https://theoldreader.com |
Hosted service with GReader-compatible API |
--greader-url is the address that the GReader API paths (/accounts/ClientLogin, /reader/api/0/...) hang off. If your reader's documentation gives a "Google Reader API" or "GReader API" URL, use that.
Metadata
Release files for rss-digest 0.0.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| rss_digest-0.0.8.tar.gz | 146.6 kB | Without provenance | Details for rss_digest-0.0.8.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| rss_digest-0.0.8-py3-none-any.whl | Python 3 | none | any | Details for rss_digest-0.0.8-py3-none-any.whl |
Total release size: 167.3 kB
Release files / rss_digest-0.0.8.tar.gz
| Download URL | rss_digest-0.0.8.tar.gz |
|---|---|
| Size | 146.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1a5ccbdbbc53e44529aac6ec2b16e8f4c6921cd64ee904d1598a7209f026ddaa
|
|
BLAKE2b-256 checksum How to use checksums |
d570e78f8cef8fef3860911a0af62f476e9f4a88daf17df9a070d0763f6e6426
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / rss_digest-0.0.8-py3-none-any.whl
| Download URL | rss_digest-0.0.8-py3-none-any.whl |
|---|---|
| Size | 20.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5de1b0bf21b556be711546bfb9c73b591c3624892df7a8e1f588e5ce2516f580
|
|
BLAKE2b-256 checksum How to use checksums |
5a3d411eab2b28f58859fa81d38439ee9da54cc6654cc97393fab92330ecf8d2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for rss-digest 0.0.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.