Help & getting started

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.

Getting started

  1. 1

    Add your first feed

    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.

  2. 2

    Read & organize

    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.

  3. 3

    Turn on AI (optional)

    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:

    • AI scoring: a more accurate relevance score, from a model that reads your interest profile, on the articles a filter labels. A handy trick: add a filter that marks low-score articles as read, so they never clutter your list.
    • Summaries and chat over any article.
    • Catch me up & briefings: a digest of what you missed over a period, on demand or scheduled to your inbox.

Getting around the reader

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.

Row actions in the sidebar
Hover over a feed, folder, label or one of the views at the top and two small buttons appear on the right: ↻ fetches that feed right away, ✓ marks everything as read. The ✓ always applies to the row you're on, so it works per feed, per folder, per label, or for all articles at once. On a touchscreen, press and hold the row instead of hovering.
Folding things away
The small arrow next to a folder or next to Labels collapses that group. The arrow in the sidebar header collapses the whole sidebar into a narrow strip of icons, which keeps your navigation one click away without taking up a panel.
The ··· menu on an article
Next to the article's date sits a ··· button. It holds everything beyond plain reading: star, archive, mark read or unread, share, copy the text, and, if the article came in as a bare headline, Extract full content to pull the full text from the original page. With an AI key it also offers the summary, context and chat.
The line under an article in the list
When several of your feeds file the same story, Readfine keeps one row for it and puts a line underneath saying how many other sources covered it and how many of those you have read. The line opens them as rows indented under the first one. See Several of my feeds carry the same story.
Search from anywhere
Press / to open search without reaching for the mouse, or use the magnifier in the sidebar header. You can scope a search by feed, folder, label, read status, your starred, saved or archived articles, score and how recently it was published (the last day, week, month and so on), and sort the results, best score first if you like. A search with no words and just a score condition gives you a list of your best articles. Chinese, Japanese and Korean words are found inside running text too, and so are Thai, Lao, Khmer and Burmese ones, though a search for a single character only looks at titles. Save in the results header keeps a search in the sidebar; see How do saved searches work?. Besides Unread and Read, which follow the read mark (scrolling past sets it too), the status can be Actually read or Not actually read: 30 seconds on the article or its original opened, as in Stats. Not actually read with a score of 70 and up is a list of the good ones you missed. Accents don't matter, English words match in their other forms (votes finds voting), and a word ending in * finds every word it begins: cycl* finds cycling and cyclist. Esc closes it.
Keyboard shortcuts

The keys are the ones Inoreader and Miniflux use, and the TT-RSS ones work too. Press ? in the reader to see this list.

All shortcuts

Moving around

jorn
Next article
korp
Previous article
oorEnter
Open the article, or close it in the 2-panel layout
Space
Read on: a screen down, then the next article
Shift+J
Next entry in the sidebar
Shift+K
Previous entry in the sidebar
gthena
Go to All articles
gthens
Go to Starred
r
Reload the list
/
Search

The open article

moru
Mark read or unread
sorf
Star or unstar
e
Archive or unarchive
torl
Labels
v
Open the original in a new tab

The list

Shift+A
Mark everything in this view as read
?
Show this list
Esc
Close a window
Keeping an article that isn't in your feeds
Open Saved in the sidebar and paste a link into the bar at the top of the list. See What is Saved?

A workflow that works well

There's no single right way to use Readfine, but here's one that scales nicely once you follow a lot of feeds:

  • Let filters (and, with AI, scoring) do the triage: auto-label what matters, mark the rest as read, then browse your labeled articles instead of wading through one long unread list.
  • Keep a saved search for what scores best. If you listed your topics when you signed up, Top picks in the sidebar is one already: the last week's articles scoring 60 or more, best first. Otherwise search with a relevance condition and choose Save in the results header.
  • Treat the star as a read-later queue: star anything worth a proper read, then come back to your starred list when you have time, rather than reading everything the moment it arrives.

FAQ

Jump to a question

Setting up

Can I import from another reader?

Yes. Export an OPML file from your current reader and import it in Settings → OPML. You can also export your Readfine subscriptions there.

What's a scrape feed?

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.

What is relevance scoring?

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.

How does basic relevance match my terms?

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.

  • The words of one term add up. With the term 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.
  • Separate terms don't add up. An article scores by the one term it matches best. Written as two terms, 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.
  • Rare words weigh more. A word that appears in few articles tells more than one that is everywhere, so 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.
  • Related forms are found on their own. 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.
  • Other languages are just more terms. If you read in two languages, add the translation: 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.

How do filters work?

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:

  • Basic: the basic score. Every article has one as soon as it arrives, so the filter runs with the others, in run order. It ignores AI scores, so an article the AI rated highly still matches on its basic score. To go by the AI score where there is one, use AI, else basic. A threshold of 70 lets through about one article in ten.
  • AI: the AI score. Only articles a label filter sent to AI scoring have one, and the filter runs once the score is in.
  • AI, else basic: the relevance score, the same number the article list shows. The filter runs right after the others, unless one of them sent the article to AI scoring; then it waits for the AI score, and uses the basic score if scoring fails. A label it adds sends the article to AI scoring like a label from any other filter.

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.

Do I still need keyword filters if I have terms?

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:

  • Picking out what interests you. Terms can take this over. A single filter Basic at least 50 → add a label labels whatever matches your terms, and the label sends it to AI scoring. You keep one list of terms instead of a keyword list in every filter.
  • Sorting into topics you browse by label, such as Cycling or Baking. Keep these filters. The score is a single number and can't tell one topic from another.
  • Fixed rules, such as labeling everything from one feed or marking sports results or shopping deals as read. Keep these too. Terms have no regex, can't exclude anything and only look at the title and the opening of an article.

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.

How do I use regex in a filter?

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.

Reading

How do I customize the layout?

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.

Several of my feeds carry the same story. What does Readfine do?

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.

What is Saved?

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.

How do saved searches work?

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.

Can I install Readfine as an app?

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.

Can I share an article?

Yes. Share in the article's ··· menu creates a link that works without signing in, so you can send it to someone who has no Readfine account. Anyone holding the link can read that one article, so treat it as public. The same menu shows the link once it exists, along with Revoke, which kills it immediately. Nothing else about your account is exposed, and no article is shared until you ask for it.

Where do I see how I'm reading?

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.

AI

Where do I get an AI key?

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?

Can I use my own model or another provider?

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.

  • Ollama's endpoint needs the /v1 suffix (http://localhost:11434/v1); llama.cpp's server does not.
  • One endpoint per account, shared by both slots. Each slot still picks its own model, so a small model can score while a larger one writes summaries, as long as both live on the same server.
  • Self-hosting on a private address (localhost, a Docker network) means naming that address in 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.
  • A thinking model is fine, including on both slots. Scoring answers with one number in ten tokens, so a model that reasons first would spend all ten on that; Readfine therefore asks the endpoint to skip reasoning for scoring, which Ollama, llama.cpp and vLLM all understand. Summaries and chat have room to think and are left alone, so one capable model can serve both slots. If your server is too old to know the request, saving the model says so instead of leaving articles unscored.
  • First Verify after a cold start can time out while the server loads the model into memory. Try it once more.
  • Small models have small context windows. If yours is 4k or 8k tokens, lower Article content limit in Settings → AI from its 20 000 character default.
  • Costs can't be shown for your own endpoint: the tokens are counted, the price column stays empty.

How do Catch me up & briefings work?

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.

Your data

How long are articles kept?

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.

Is there an API?

Yes, a JSON API for scripts and integrations. Create a token in Settings → Tokens and send it as a bearer token.

Is my data private?

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.

When something goes wrong

A feed shows a red marker. What now?

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.

Articles from while I was away are missing

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.