AI Web FeedsAI Web FeedsOpen web AI reader
Guides
Documentation

Getting Started

Install the repo, run the web app, and generate the article library with the required uv and pnpm workflows.

Source: apps/web/content/docs/guides/getting-started.mdx

This guide takes you from a fresh clone to a working local setup.

Prerequisites

  • Python 3.13+
  • Node.js 20+
  • uv
  • pnpm
  • Git

Clone the repo

git clone https://github.com/wyattowalsh/ai-web-feeds.git
cd ai-web-feeds

Install Python dependencies

uv sync

Install the web app dependencies

cd apps/web
pnpm install
cd ../..

Build the article library

uv run ai-web-feeds corpus refresh

This populates the runtime data and writes data/articles.generated.json, which powers the main Feeds experience.

Start the web app

cd apps/web
pnpm dev

Open http://localhost:3000 and start in /.

Once the project is running, start at /reader for the canonical reader. Switch to /sources for source refinement, and open /dashboard for catalog health. These docs pages are the best next stops after that:

Useful Next Commands

uv run ai-web-feeds validate http
uv run ai-web-feeds enrich all \
  --input data/feeds.yaml \
  --output data/feeds.enriched.yaml \
  --schema data/feeds.enriched.schema.json \
  --database sqlite:///data/ai-web-feeds.db

Where to Go Next

Working With data/feeds.yaml

The repository already includes a curated catalog in data/feeds.yaml. When you want to add or edit sources, update that file first and then rerun the enrichment and validation commands above.

Example entry:

sources:
  - id: my-custom-feed
    feed: https://example.com/feed.xml
    title: My Custom Feed
    source_type: blog
    topics: [llm]
    tags: [custom]

Troubleshooting

Missing Tooling

If uv or pnpm is missing, install them before continuing. The repository policy explicitly avoids bare python, pip, npm, and yarn workflows.

Reset the Local SQLite Cache

bash scripts/setup.sh

If you need a completely fresh local cache, remove data/ai-web-feeds.db and run the setup script again. The codebase still recognizes the legacy data/aiwebfeeds.db filename if an older local install already exists.

YouTube channel

GitHub repository


See the [Platform Integrations](/docs/features/platform-integrations) guide for more details.

### Monitoring Feed Health

Set up regular health checks:

```bash
# Check all feeds
ai-web-feeds fetch all --verified-only

# Review performance
ai-web-feeds analytics performance --days 7

# Check specific feed health
ai-web-feeds analytics health <feed-id>

Exporting Data

Export to different formats:

# OPML for feed readers
ai-web-feeds opml generate --output feeds.opml

# Categorized OPML
ai-web-feeds opml categorize --output feeds-categorized.opml

# JSON analytics report
ai-web-feeds analytics report --output analytics.json

Configuration

Database Configuration

By default, SQLite is used. To use a different database:

ai-web-feeds fetch all --database "postgresql://user:pass@localhost/dbname"

Or set an environment variable:

export AI_WEB_FEEDS_DB="postgresql://user:pass@localhost/dbname"

Fetch Configuration

Create a config file (e.g., .env):

AI_WEB_FEEDS_TIMEOUT=30
AI_WEB_FEEDS_USER_AGENT="MyApp/1.0"

Troubleshooting

Common Issues

Feed Not Found Error

# Verify feed exists in database
ai-web-feeds stats show

# Check feeds.yaml for typos
cat data/feeds.yaml | grep "id:"

Fetch Failures

# Check error details
ai-web-feeds analytics performance

# Test single feed with verbose output
ai-web-feeds fetch one <feed-id> --metadata

Database Issues

# Reinitialize database
rm data/aiwebfeeds.db
python3 -c "
from ai_web_feeds.storage import DatabaseManager
db = DatabaseManager('sqlite:///data/aiwebfeeds.db')
db.create_db_and_tables()
"

Next Steps

  1. Explore Analytics - Try different analytics commands to understand your feed data
  2. Set Up Automation - Create cron jobs for regular fetching
  3. Customize Feeds - Add feeds relevant to your interests
  4. Build Integrations - Use the Python API to integrate with other tools
  5. Contribute - Share your curated feeds with the community

Example Session

Here's a complete example workflow:

# 1. Install
./setup-enhanced-features.sh

# 2. Check what's in the database
ai-web-feeds stats show

# 3. Enrich existing feeds
ai-web-feeds enrich all

# 4. Fetch content
ai-web-feeds fetch all --limit 10

# 5. View analytics
ai-web-feeds analytics overview
ai-web-feeds analytics distributions
ai-web-feeds analytics quality

# 6. Check a specific feed
ai-web-feeds analytics health huggingface-blog

# 7. Generate reports
ai-web-feeds analytics report --output report.json
ai-web-feeds opml generate --output feeds.opml

# 8. View trends
ai-web-feeds analytics trends --days 30

What's Next?

Now that you're set up, you can:

  • Add more feeds to your collection
  • Set up automated fetching (cron jobs)
  • Build custom analytics scripts
  • Integrate with other tools
  • Contribute back to the project

Resources

Happy feed aggregating! 🚀

On this page

PrerequisitesClone the repoInstall Python dependenciesInstall the web app dependenciesBuild the article libraryStart the web appUseful Next CommandsWhere to Go NextWorking With data/feeds.yamlTroubleshootingMissing ToolingReset the Local SQLite CacheYouTube channelGitHub repositoryExporting DataConfigurationDatabase ConfigurationFetch ConfigurationTroubleshootingNext StepsExample SessionWhat's Next?Resources
Getting Started | AI Web Feeds