NeuReed is an RSS reader that actually understands what you read. Using AI and semantic search, it learns your interests and surfaces content you'll actually care about. No more drowning in feeds - just the good stuff.
- 🤖 AI That Gets You: The more you read, the better it understands your interests
- 🔍 Search That Actually Works: Find articles by meaning, not just keywords
- 🎨 Beautiful & Customizable: Dark mode, themes, reading preferences - make it yours
- 🚀 Blazing Fast: Built on Next.js 16 with pgvector for instant semantic search
- 💰 Cost-Aware: Track your OpenAI usage or use free local models
- 🔐 Privacy First: Self-hosted, your data stays yours
Type "machine learning tutorials for beginners" and get relevant articles even if they never used those exact words. That's the power of vector embeddings.
- Thumbs up articles you love, thumbs down ones you don't
- NeuReed learns from your reading patterns automatically
- Get personalized article scores based on your interests
- Articles you'll love float to the top
- OpenAI GPT models: Powerful summaries and embeddings
- Local models: Zero cost, complete privacy
- Bring your own: Use any OpenAI-compatible endpoint
- Per-feature models: Different models for summaries vs embeddings
- Organize feeds into categories that make sense
- Set refresh intervals per feed, category, or globally
- OPML import/export for easy migration
- Automatic cleanup of old articles
# Clone and setup
git clone https://github.com/madpin/neureed.git
cd neureed
./scripts/setup.sh
# Start developing
npm run devThe setup script handles everything: environment files, Docker containers, dependencies, database setup, and even sample data if you want it.
# Start everything (app + database)
docker-compose up -d
# Check it out
open http://localhost:3000Click to expand manual setup
# Install dependencies
npm install
# Create environment file
cp .env.example .env.local
# Start PostgreSQL with pgvector
docker-compose up -d postgres
# Setup database
npx prisma migrate dev
npx prisma db seed
# Start the app
npm run dev- Sign in with GitHub or Google (or configure another OAuth provider)
- Add some feeds - click the + button in the sidebar
- Read stuff - articles auto-refresh every 30 minutes
- Give feedback - thumbs up/down to train your personal AI
- Try semantic search - type naturally, get smart results
Split-pane reading interface |
Main article list with feed filtering |
Full-page article reading experience |
Compact sidebar for more reading space |
System statistics and health monitoring |
Vector embeddings coverage and status |
User roles and permissions |
Background job execution and logs |
Database and Redis storage metrics |
Default preferences for new users |
Quick access to preferences and settings |
User profile and authentication info |
Multiple theme options (light, dark, and more) |
Customize article density and visibility |
Fine-tune borders and spacing |
Configure split-pane reading experience |
AI learning preferences and pattern detection |
Personal LLM configuration and API keys |
NeuReed comes with a variety of beautiful themes to match your style and mood:
Light |
Dark |
Nord Light |
Nord Dark |
Solarized Light |
Solarized Dark |
Barbie Light |
Barbie Dark |
Purple Light |
Purple Dark |
Orange Light |
Orange Dark |
Rainbow Light |
Rainbow Dark |
Advanced feed settings and organization |
System-wide LLM provider configuration |
- Semantic search: Find articles by meaning, not keywords
- Saved searches: Create persistent queries that auto-match new articles
- Related articles: Discover content similar to what you're reading
- Personalized scoring: Articles ranked by how much you'll like them
- Smart filtering: Hide read articles, filter by feed or category
- Three reading modes: Choose how you consume content
- Side Panel: Split-screen with resizable panel (classic view)
- Inline: Accordion-style expansion directly in the article list
- Standalone: Full-page dedicated reading experience
- Customizable fonts: Size, family, line height, spacing - all yours
- Theme variety: Light, dark, Nord, Solarized, and more fun themes
- Auto-scroll option: Automatically scroll to expanded articles in inline mode
- Estimated reading time: Know before you commit
- Drag & drop: Organize feeds intuitively
- Category management: Group feeds however makes sense to you
- Per-feed settings: Different refresh rates, retention policies
- OPML support: Import/export your subscriptions
- Dynamic feeds: Create searches that continuously monitor all your articles
- Advanced syntax: Use AND/OR/NOT operators and grouped queries
- Relevance scoring: See how well each article matches your query
- Smart notifications: Get alerted only for high-relevance matches
- Templates: Start quickly with pre-built search patterns
- Mobile optimized: Swipe gestures, offline support, responsive design
- Article summaries: TL;DR powered by GPT
- Embedding generation: Automatic or on-demand
- Cost tracking: Know exactly what you're spending on AI
- Provider flexibility: OpenAI, local models, or custom endpoints
- Cron job management: Monitor and trigger background tasks
- Embedding stats: Track coverage and generation progress
- User management: See who's using your instance
- System health: Cache status, database stats, and more
- Getting Started - Complete documentation index
- Saved Searches User Guide - Master dynamic content monitoring
- Saved Searches Feature Spec - Complete feature documentation
- Deployment Guide - Deploy to production
- Configuration Reference - All the settings
- API Documentation - If you're building integrations
- Architecture Docs - How it all works
We're standing on the shoulders of giants:
- Next.js 16 - The React framework
- PostgreSQL + pgvector - Vector similarity search
- Prisma - Type-safe database access
- NextAuth.js - Authentication that just works
- TanStack Query - Data fetching & caching
- Tailwind CSS - Styling without the pain
- Redis - Caching layer for speed
Found a bug? Have an idea? Contributions are welcome!
# Fork the repo, then:
git clone https://github.com/YOUR_USERNAME/neureed.git
cd neureed
npm install
./scripts/setup.sh
# Create a feature branch
git checkout -b feature/amazing-feature
# Make your changes, commit, and push
git commit -m "Add some amazing feature"
git push origin feature/amazing-feature
# Open a PR!Here's what you'll need for a basic setup:
# Database (required)
DATABASE_URL="postgresql://user:pass@localhost:5433/neureed"
# Auth (required for login)
NEXTAUTH_SECRET="generate-with-openssl-rand-base64-32"
NEXTAUTH_URL="http://localhost:3000"
# OAuth (pick at least one)
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-secret"
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-secret"
# AI Features (optional but recommended)
OPENAI_API_KEY="sk-your-api-key"
# Redis (optional, but makes things faster)
REDIS_URL="redis://localhost:6379"See Configuration Reference for the complete list.
Database connection fails?
- Make sure PostgreSQL is running:
docker-compose ps - Check the port (we use 5433 to avoid conflicts)
Build fails?
- Clear node_modules and try again:
rm -rf node_modules && npm install - Make sure you're on Node.js 24+:
node --version
Embeddings not working?
- Set your OpenAI API key or enable local embeddings
- Check admin dashboard → Search tab for provider status
Still stuck? Check GitHub Issues or create a new one.
MIT License - see LICENSE file for details. Build cool stuff with it!
- Built with ❤️ by developers who got tired of crappy RSS readers
- Inspired by the need for actually intelligent content discovery
- Powered by the amazing open-source community
If NeuReed makes your RSS reading life better, give us a star! It helps others discover the project.
Ready to take control of your content? Get started now! 🚀