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 canonical local SQLite asset is data/ai-web-feeds.db.

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
uv run ai-web-feeds fetch all --verified-only

# Review performance
uv run ai-web-feeds analytics summary --date-range 7d

# Check specific feed health
uv run ai-web-feeds validate http --feed-id <feed-id>

Exporting Data

Export to different formats:

# OPML for feed readers
uv run ai-web-feeds opml all --output feeds.opml

# Categorized OPML
uv run ai-web-feeds opml categorized --output feeds.categorized.opml

# Analytics CSV report
uv run ai-web-feeds analytics export --output analytics.csv

Configuration

Database Configuration

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

uv run 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
uv run ai-web-feeds stats show

# Check feeds.yaml for typos
rg "id:" data/feeds.yaml

Fetch Failures

# Check error details
uv run ai-web-feeds analytics summary

# Test single feed polling
uv run ai-web-feeds fetch one <feed-id>

Database Issues

# Reinitialize database
rm data/ai-web-feeds.db
uv run python -c "
from ai_web_feeds import DatabaseManager, upgrade_database_to_head
database_url = 'sqlite:///data/ai-web-feeds.db'
upgrade_database_to_head(database_url)
db = DatabaseManager(database_url)
"

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 summary
ai-web-feeds analytics trending
ai-web-feeds analytics velocity

# 6. Check a specific feed
ai-web-feeds validate http --feed-id huggingface-blog

# 7. Generate reports
ai-web-feeds analytics export --output report.csv
uv run ai-web-feeds opml all --output feeds.opml

# 8. View trends
ai-web-feeds analytics trending --date-range 30d

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