A quick guide to Readfine: how to set it up, how to get around the reader, and answers to the questions that come up most. For a complete rundown, see the full feature list.
Paste an RSS/Atom feed URL in Settings → Feeds. Readfine can also scrape a website that has no RSS, see What's a scrape feed? below.
If someone on this server already reads the feed, it comes with the articles it has collected. You get the last week unread (at least the newest ten), and older ones as read, so you can still find them in the feed and in search.
Coming from another reader? Import your subscriptions via OPML.
Articles open in a clean reading view. Mark them read, star favourites, or archive what you want to keep out of the way.
Relevance scores every article by how well it matches what you follow, with no API key: list a few specific topics in Settings → Relevance (see How does basic relevance match my terms?).
Labels are your own colour-coded tags for sorting articles by hand. Create them in Settings → Labels.
Filters do the tagging for you: each new article is checked against your rules and, when the conditions match, actions are applied automatically (add a label, mark as read, star, archive). Set them up in Settings → Filters (see How do filters work?).
That's everything you need for day-to-day reading.
AI features are an optional layer. They use your own API key (Anthropic, OpenAI or Google), which you add in Settings → AI. See Where do I get an AI key? You can also run the models yourself, with no key at all, over your own endpoint.
Once enabled you get:
Most of the reader is where you'd expect it. These few things are worth pointing out, because they only show up once you go looking.
The keys are the ones Inoreader and Miniflux use, and the TT-RSS ones work too. Press ? in the reader to see this list.
There's no single right way to use Readfine, but here's one that scales nicely once you follow a lot of feeds:
Yes. Export an OPML file from your current reader and import it in Settings → OPML. You can also export your Readfine subscriptions there.
When a website has no RSS feed, Readfine can read its listing page directly. You point it at the page and give a CSS selector that matches the article links; Readfine then checks that page on a schedule, just like an RSS feed. If you have an AI key, it can suggest the selector for you. Start by pasting the site URL in Settings → Feeds.
Readfine can score every incoming article by how well it matches what you follow. There are two scorers.
Basic relevance needs no API key. It looks for your terms, a list you keep in Settings → Relevance, in the title and opening of each article. It matches words rather than meaning, so it is the weaker of the two; how it matches.
AI scoring rates labeled articles against your interest profile, a short description of what you care about, which you write yourself or have the AI generate from the articles you've read, in Settings → AI. Where both have a score, the AI one counts: the relevance score is the AI score where an article has one and the basic score otherwise. That is the number the article list shows (unless a search picked one scorer, then it shows that one) and Catch me up samples by. Combine scoring with a filter (e.g. mark anything below a threshold as read) to keep your list focused; which score a filter reads.
Terms are separated by commas, semicolons or new lines, all three alike. The list is kept exactly as you wrote it in Settings → Relevance. Saving a changed list rescores your unread articles from the last 7 days within a few minutes, and new articles are scored as they arrive.
urban cycling, an article titled
"Madrid opens new urban cycling routes" scores higher than "Urban housing costs rise", which has only one
of the two words. The words don't have to stand next to each other or in that order.urban, cycling, the Madrid article would score only by its better word, no higher than
any article that just mentions cycling. So keep the
words of one topic together and put different topics apart.sourdough counts for more than bread. The same goes for your terms: specific ones
work better than general ones, since health on its own matches a large share of everything
that arrives.cycling also matches
cyclist and cyclists, at half the weight of an exact match. The same works in
languages with many word endings, such as Czech or Polish, with no language setting.cycling, ciclismo. Chinese, Japanese and Korean terms work too, and must appear in the article
as written. Thai, Lao, Khmer and Burmese don't work yet: they write without spaces between words, and
the score can't tell where a word ends.It looks at the title and the first 300 characters of each article and matches words, not meaning: it cannot tell that a report from the Tour de France is about cycling unless one of your terms appears in the report. That is why it is the weaker of the two scorers.
Suggestions. Below the list, Readfine suggests words that keep coming up in articles you read (for half a minute, or opened or starred) in the last 30 days, and terms of yours that match many articles you then skip. A click adds or removes the term and saves the list. Why these? shows the headlines behind each suggestion, and Hide for 3 months there puts one away; it can come back after that. Suggestions appear once you have read ten articles that way.
How your terms did. A table under the list shows, for each term, how many articles it matched in the last 30 days, how many of those you read, and how that compares with your average. At 3× you read what the term picks three times as often as the rest of your feeds; around 1× it picks no better than chance. A term with no match may be too narrow. "Not counted yet" means its words are too rare in the last month's articles to score: it may be misspelled, or new to your feeds, since words from a feed added today are counted overnight. If your feeds bring in more than 5,000 articles in 30 days, the table and the suggestions look at the newest 5,000 (but never less than a week), and the table says how many days that is.
A filter is a set of conditions (match on title, content, author, score… with AND/OR and optional regex) plus actions that run when an article matches: add a label, mark as read, or star. You can scope a filter to specific feeds or folders. Filters run on new articles as they arrive. Manage them in Settings → Filters.
Filters run by their run order, from the lowest number up, and filters with the same number run in name order. It matters with Stop on match: a matching filter with it ticked keeps the filters after it in the same group from running on that article. Filters on the AI and the AI, else basic score form their own group, listed below the others. They run after the rest, so a Stop on match in the first group does not stop them.
A new filter only sees articles that arrive after you save it. To catch up on what's already in your list, use Apply next to the filter, which runs it over your existing articles once and shows you what it will do before anything is committed. Test next to it checks the conditions against your articles without changing a thing.
A score condition is at least or below a number from 0 to 100, compared like in the search: at least 60 takes in every article the list shows as 60 or more. It reads one of three sources, and the source also decides when the filter runs:
Each filter runs once per article. A condition whose scorer is off never matches; the filter stays as it is and is marked in the list.
Fewer than you might think. Your terms already rate every article as it arrives, so one filter on the basic score can do the work of a pile of keyword filters. It helps to ask what each of your filters is for:
Exact names are also safer in a filter. A term matches loose words, while a filter matches the text exactly or by regex. And the basic score is the weaker scorer, so a low threshold lets some misses through. With AI scoring on, that is fine: the AI score sorts them out afterwards.
With both scorers, the labeling filter and a cleanup filter work well together. Label at a lower basic score than the cleanup protects, for example label at 50 and clean up with AI below 30 AND Basic below 60 → mark as read. Articles from 50 to 59 go to the AI and it decides. From 60 up, your terms vouch for the article and it stays even if the AI disagrees.
That safety net matters most where your terms and your interest profile differ. A topic that is in your terms but missing from the profile (or listed there among things to avoid) gets a low AI score, and only the basic score keeps it in the list. If the topic matters to you, add it to the profile as well. Which score a filter reads.
When a condition's operator is regex, the value is treated as a regular
expression (Python syntax). The pattern is matched anywhere in the field and is
case-insensitive, so einstein also matches “Einstein”.
Use it on text fields (title, content, author, URL) when plain contains isn't enough.
(apple|pear|fig) matches any of several terms (OR).\bAI\b matches the whole word “AI” only (not “rain” or “maintain”);
\b is a word boundary. Chinese and Japanese write without
spaces, so there \b sees a whole sentence as one word; leave it out and
the word is found anywhere in the text.^Breaking means the field starts with “Breaking”
(^ = start, $ = end).colou?r matches “color” and “colour”
(? = the previous item zero or one time).\d{4} matches exactly four digits, e.g. a year like “2026”
(\d = a digit, {4} = four times).Building blocks you can combine:
. any character,
\d digit,
\w letter/number,
\s space,
* zero or more,
+ one or more,
[a-z] a range. Special characters
(. $ ^ ( ) [ ] * + ?) must be escaped with a backslash to match
them literally, e.g. \$\d+ matches a price like “$50”.
Patterns are limited to 200 characters, and a few
constructs prone to catastrophic backtracking (nested quantifiers like
(\w+)+) are rejected when you save. An invalid pattern is reported
on save, so nothing breaks silently.
New to regex? Build and test patterns interactively at regex101.com. Pick the Python flavor to match how Readfine evaluates them.
Open Settings → Preferences to choose a 2- or 3-panel layout (separately for medium and large screens), the list density (compact, comfortable or summary, separately for desktop and mobile), dark mode, and whether articles are marked read as you scroll. You can also choose how the sidebar behaves on small screens (collapsible or hideable), and where the breakpoints between screen sizes sit.
The same page holds the smaller things that shape day-to-day reading: the font family and text size of the reading view, your timezone and how dates and numbers are written, the default sort order and how many articles load at a time, whether the list starts filtered to unread, whether Readfine jumps to the next feed after you mark everything read, and whether an article that carries only a headline opens the original page straight away.
It keeps one row for the story instead of five. Readfine compares the headlines of articles that arrive within 72 hours of each other and from different feeds, which catches the same event written up by five newsrooms under five addresses and five headlines. One article stays in the list, with a line under it saying how many other sources covered the same thing and how many of those you have already read. Two articles from the same feed are never grouped: a newsroom filing twice is usually an update or a correction, not a duplicate.
It errs towards leaving coverage apart. An article joins a story when it resembles the story as a whole, not just one headline in it, so where two newsrooms write up one event in words that barely overlap you sometimes get two rows instead of one. That is the safer way round: a row that should have folded costs you a line, while a group that should not have formed puts one piece of news under a headline about another, and can take an article away from you if you have the second option below turned on.
That line opens the rest of the group in place, as ordinary rows indented under the first one, so they read, star and open like any other row. Where the list is already filtered, by a label, a folder or a search, opening it hands back only the articles that belong there; if the story reaches further than that, the line says so instead, "2 of 7 other sources" rather than "7 other sources". The article's own footer always shows the whole group, filtered view or not. Reading the row finishes the story: the articles behind it are marked read too, so the same event stops coming back as unread in a label, a feed or a search. Marking the row unread again brings them back, and a group you have unfolded is read one article at a time. Only feeds you subscribe to are ever counted or listed.
In Settings → Preferences you can turn this off, or take it one step further. With Fold, and don't show a story I've read again, an article that repeats a story you have read arrives already marked as read, so it stays out of your unread list. It is not deleted: it is under the article you read, in All, and in search. The setting also says how many articles it kept out in the last 7 days, and that count opens onto the articles themselves, each with the headline it was kept out for repeating, so you can check the calls it made. Only articles you read yourself count: clearing a backlog with Mark all read says you are not going to read those, so nothing is ever kept out on their account.
Catch me up and briefings fold the same stories. One article of each goes into the digest, and the model is told how many other sources you take covered it, so five write-ups of one event no longer take five of the places a digest has. It shows up most in a digest over a week or more, where there is more news than fits; a digest of a single day rarely has anything to fold yet. A briefing narrowed to one feed folds nothing at all, since the grouping only ever pairs articles from different feeds, but the coverage is still counted. With the second setting on, an article kept out of your unread list stays out of your digests too.
Where a headline says outright that it is a later piece, asking how or why something happened, or reporting that someone has now joined in, it is grouped with the story but never kept out of the list. It covers the same news and is not the same article.
That last option is off unless you ask for it, because the match is lexical. Comparing headlines cannot tell "another source on the same event" from "the next development in it", so now and then it catches a follow-up rather than a repeat. Folding only ever moves such an article one tap away; hiding it means you may not see it at all, which is a bigger thing to hand over to a guess. Starred, saved, archive and a single feed's own list are left alone either way, and marking a feed or folder read never reaches beyond it.
Saved is for articles that aren't in any of your feeds. Open it in the sidebar, paste a link into the bar at the top of the list, and Readfine fetches the page and runs it through the same readable extraction as a normal article. Saved articles stay until you remove them, so retention never takes them away.
You can also save a page while you are on it. On a computer, drag the Save bookmarklet from Settings > Preferences to your bookmarks bar, then click it on any page and press Save. On Android, the installed app does the same from the share sheet.
Run a search, then choose Save in the header above the results and give it a name. It appears in the sidebar above Labels, with its count, and stays there until you delete it. A saved search is not a snapshot: each time you open it, it runs again over your articles as they are now, so a search for a topic keeps picking up new coverage of it.
Opened from the sidebar, a saved search behaves like a feed. Articles are marked read as you scroll past them, and Mark all as read (the tick that appears when you hover the row) marks only what the search lists. If you saved it with a status, such as Unread or Not actually read, it keeps to that status. Without one, it follows your unread setting, the same as a folder does.
Edit in its header reopens the search window with everything filled in. Change what you like, then save the changes into it, save them as a new search, rename it or delete it. A search needs at least a word or one filter to be saved; the sort alone is not enough.
If you delete a feed, folder or label a saved search used, it is taken out of the search. When it was the only one, the search keeps it and finds nothing until you change it, rather than quietly widening to all your articles. Its Edit window says so.
A new account that lists its topics on the welcome screen starts with one, Top picks: the last week's articles with a relevance score of 60 or more, best first. It is an ordinary saved search, so you can change it or delete it. The count next to a saved search is left out when counting it would take too long, which can happen with a search over a lot of labelled articles.
Yes, on a phone and on a desktop alike. In Chrome or Edge it is Install app in the browser menu; on an iPhone or iPad it is Share, then Add to Home Screen. It opens in its own window with no address bar, and it is the same Readfine, with nothing stored offline. On Android you also get Readfine in the share sheet: sharing a link from any other app adds it to Saved. Sharing is not available on iOS, which does not offer it to web apps.
Running your own instance, this needs HTTPS. Browsers do not offer to
install a site served over plain http://,
so an instance reachable only on a local address such as
http://192.168.0.10:8000 will never
show the option, with nothing to say why. The one exception is
localhost, which browsers trust on
the machine itself.
Settings → Stats shows what you actually get through: read rate, reading streak, how long you spend on an article, and your most active day and hour. It shows how relevance scores are spread over what arrives, and with an AI key it also checks how well the AI scores line up with your real reading, points out missed gems the AI rated highly but you never opened, and estimates what your AI usage costs.
Readfine is bring-your-own-key: you create a key with one of the providers and paste it into Settings → AI. It's stored encrypted and used only for your own requests.
Running a model yourself needs no key at all, see Can I use my own model?
Yes. Pick Custom (OpenAI-compatible) as the provider in Settings → AI and fill in the Endpoint field. Anything that speaks the OpenAI API works: Ollama, llama.cpp's server, LM Studio, vLLM, a LiteLLM proxy, or a gateway like OpenRouter. Leave the API key blank for a local server that doesn't ask for one.
/v1 suffix
(http://localhost:11434/v1); llama.cpp's server does not.AI_ALLOWED_PRIVATE_HOSTS in the instance's environment,
as host and port: AI_ALLOWED_PRIVATE_HOSTS=ollama:11434,
comma-separated for more than one. Anything not on that list has to be a public address, which is
what keeps a hosted instance from being talked into calling its own internal services.Catch me up generates an on-demand digest of articles from a period and scope you choose. A briefing is the same thing on a schedule, delivered to your inbox. Both need an AI key. Set them up under Catch me up & briefings in the reader.
Old articles are cleaned up automatically so the archive doesn't grow forever. The exact window is set by whoever runs the instance and is written out at the bottom of Settings → Feeds. Anything you starred, archived or saved by URL is kept indefinitely, so marking an article in any of those ways is how you make sure it stays.
Yes, a JSON API for scripts and integrations. Create a token in Settings → Tokens and send it as a bearer token.
Your account, feeds and API keys are yours alone; keys are stored encrypted. See the Privacy Policy for details on what data is held and your rights.
That means the last fetch failed. Hover the marker to see why: a site that moved, a feed URL that no longer exists, a temporary outage. Hit ↻ on the feed row to retry right away; if it succeeds, the marker disappears. When the address has genuinely changed, correct it in Settings → Feeds: open the feed and edit Feed address. Everything the feed already holds stays where it is, articles included, and the new address is fetched once before it is saved. On an instance where somebody else follows the same feed, the address is the administrator's to change. The same page is where you set a custom title, move the feed into a folder, adjust how often it's checked, and store credentials for a feed that sits behind a login.
An instance can stop fetching feeds whose readers have all been away for a long time. The administrator sets how long, and if mail is set up you get an email a week before it happens. Your feeds, folders, labels and filters stay as they are. Once you are back, fetching starts again within about 15 minutes, but articles a site published and then dropped from its feed during the pause are not recovered.