Skip to main content
══════════════════════════
    R S S  D I G E S T
══════════════════════════

CI

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.

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.

  1. Download and open LM Studio, load a model (Mistral, Llama, Gemma, etc.)
  2. Start the local server: Local Server tab → Start Server
  3. Copy the [model identifier] shown in the UI (e.g. google/gemma-4-12b-qat)
  4. Invoke rss-digest with the --model parameter, but prefixing the model identifier with openai/, 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)

Source distribution for rss-digest 0.0.8
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)

Table of built distributions (wheels) for rss-digest 0.0.8
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page