RSSMonster

Overview

RSSMonster is not just another RSS reader — it is an intelligent reading engine designed to help you cut through information overload and focus on what actually matters.

Where traditional RSS aggregators like Feedly and Inoreader primarily deliver chronological lists of articles, RSSMonster takes a fundamentally different approach: it understands, evaluates, and prioritizes content on your behalf — transparently and under your control.

RSSMonster combines advanced search expressions, semantic clustering, quality analysis, and importance-based ranking into a system where views are declarative, not hard-coded. Instead of fixed tabs and opaque algorithms, you define what matters using composable queries that power dynamic Smart Folders such as:

Top Stories Today — importance-ranked, deduplicated coverage
Worth Your Time — high-quality, original long-form content
Quick Scan — summary-first daily overview
Low Noise Mode — maximum signal, minimal volume

Every ranking decision is explainable. Every view is customizable. Every signal — freshness, quality, originality, trust — is visible and adjustable.

Screenshot

Key Features

Lightweight & Responsive: Built with Vue.js 3 and Express, styled with Bootstrap 5 for a fluid experience across all devices
Google Reader-inspired UX: Automatic mark-as-read on scroll and trending content identification
Advanced Search Expressions: Composable filters using field operators (star:true, unread:false, read:true, clicked:true, seen:false, hot:true, cluster:eventCluster, cluster:topicGroup, clustercount:2, tag:tech, title:javascript), article age filters (firstSeen:24h, firstSeen:7d), quality & freshness thresholds (quality:>0.6, freshness:>=0.5), sorting (sort:ASC, sort:DESC, sort:IMPORTANCE, sort:QUALITY, sort:ATTENTION), and flexible date filters (@2025-12-14, @today, @yesterday, @lastweek, @"3 days ago", @"last Monday"). Example: title:javascript ai @today quality:>0.6 sort:IMPORTANCE
Smart Folders: Smart Folders allow you to create declarative, dynamic views of your content using composable search expressions. Examples: @today unread:true clustercount:2 cluster:eventCluster sort:IMPORTANCE (Top Stories Today), unread:true quality:>0.7 clustercount:2 cluster:eventCluster sort:QUALITY (Worth Your Time), unread:true clustercount:3 cluster:topicGroup quality:>0.8 freshness:>=0.5 sort:IMPORTANCE (Low Noise Mode).
Article Quality Scoring: Each article is automatically evaluated for promotional content, sentiment neutrality, and writing quality, producing a normalized quality score used for ranking
Semantic Deduplication & Clustering: Similar articles are grouped into clusters to reduce noise from syndication and duplicate coverage. RSSMonster builds event clusters (articles about the same concrete event) and topic groups (related events under a broader storyline), so you can read at the level of detail you want.
Uniqueness Scoring: Articles are ranked higher when they provide original coverage rather than repeated or copied content
Feed Trust Scoring: Sources earn a long-term trust score (0.0 to 1.0) based on content generation (articles per day), uniqueness, reading time, clicks, and starred items, improving ranking reliability over time. Run npm run feedtrust to calculate scores using originality (35%), quality (25%), engagement (20%), and consistency (20%)
Importance-Based Ranking: Articles are ranked using a transparent, runtime importance score combining freshness, quality, uniqueness, and feed trust — prioritizing what actually matters
RSS Feed Generation: Create custom RSS feeds from your stored articles with flexible filtering by user, feed, category, starred status, and read/unread state. Perfect for sharing curated content or syncing with other applications (accessible via /rss endpoint with query parameters)
Progressive Web App (PWA): Install on any device for native app-like experience with offline support
Drag & Drop Management: Intuitive feed organization and categorization
Dark Mode: Automatic theme switching
OPML Support: Import and export feeds in OPML format for seamless migration
Fever API Compatible: Works with popular RSS clients like Reeder (iOS)
Google Reader API Compatible: Works with apps like News+, FeedMe, Reeder, and Vienna RSS
Automated Actions: Define custom rules using regular expressions to automatically delete, star, mark as read, flag as advertisement, or mark articles as low quality
Multi-user Support: Separate accounts with personalized feeds and preferences
AI-Powered Assistant: Natural language search and feed management via Model Context Protocol (MCP)

How Ranking Scores Work (End User)

Importance: Blends freshness (recent items count more), quality, and coverage. Coverage rises when more sources report the same story. Freshness is the largest factor, so the newest high-quality, widely-covered items surface first.
Attention: Reflects how people interact with an article. A quick skim gives a small boost; reads, deep reads, and highly engaged sessions boost more. Re-opens and outbound clicks add a modest extra lift. No interaction means no attention boost.
Quality: Evaluates the article’s tone, writing, and promotional-ness. Scores for sentiment, writing quality, and advertisement detection combine into a single 0–1 quality score. Trusted feeds amplify good quality; lower-trust feeds dampen it.

Prerequisites

Node.js: Version 20.x or higher
npm: Comes bundled with Node.js
Git: For cloning the repository
MySQL: Or any compatible database (with configuration adjustments)

Installation

1. Clone the Repository

git clone https://github.com/pietheinstrengholt/rssmonster.git
cd rssmonster

2. Install Dependencies

# Install server dependencies
cd server
npm install

# Install client dependencies
cd ../client
npm install
cd ..

3. Configure Environment Variables

Copy the .env.example files to .env in both directories:

# Server configuration
cp server/.env.example server/.env

# Client configuration
cp client/.env.example client/.env

Edit server/.env:

DB_DATABASE=your_database_name
DB_USERNAME=your_database_user
DB_PASSWORD=your_database_password
DB_HOSTNAME=localhost
NODE_ENV=development

Edit client/.env:

VITE_APP_HOSTNAME=http://localhost:3000
VITE_NODE_ENV=development
VITE_ENABLE_AGENT=false  # Set to 'true' to enable AI assistant

4. Initialize Database

Run database migrations and seed initial data:

cd server
./node_modules/.bin/sequelize db:migrate
./node_modules/.bin/sequelize db:seed:all

5. Optional: Set Up Feed Crawler

You can crawl feeds in two ways:

Option A: Manual crawl from command line

cd server
DISABLE_LISTENER=true npm run crawl

This runs a synchronous crawl of all active feeds and provides a summary upon completion.

Option B: Automated crawl via cron

Add a cron job to crawl feeds every 5 minutes by calling the API endpoint:

*/5 * * * * curl http://localhost:3000/api/crawl

Note: The API endpoint runs the crawl asynchronously in the background and returns immediately without output.

6. Recommended: Rebuild Article Clusters

If you have semantic search enabled and need to rebuild article clusters from scratch:

cd server
npm run recluster

This command will:

Clear all existing article clusters
Rebuild clusters deterministically based on article embeddings
Process articles in chronological order (oldest first)

When to use this:

After bulk importing articles
When cluster quality degrades over time
After changing clustering algorithms or parameters
To fix cluster assignment inconsistencies

Note: This is a destructive operation that rebuilds all clusters. It requires articles to have embedding vectors already generated.

7. Recommended: Calculate Feed Trust Scores

Feed trust scores help identify high-quality sources based on originality, article quality, and user engagement:

cd server
npm run feedtrust

This command calculates trust scores (0.0 to 1.0) for all active feeds using:

Originality (35%): How often the feed publishes original content vs syndicated articles
Quality (25%): Average quality score of articles from this feed
Engagement (20%): User interaction (stars, clicks) with feed content
Consistency (20%): Placeholder for future enhancements

When to use this:

Periodically (e.g., weekly) to update feed rankings
After significant changes in reading patterns
To identify low-quality or spam feeds

The trust score uses exponential moving average (EMA) to smoothly adapt over time while being resistant to short-term fluctuations.

AI Assistant (Model Context Protocol)

RSSMonster includes an AI-powered assistant that enables natural language interactions with your RSS feeds. Ask questions like:

"Show me technology articles from the last week"
"What are my favorite articles?"
"Find unread posts about JavaScript"