1<h1 align="center">llm_aggregator</h1>
  2
  3<p align="center">
  4    <img src="assets/logo.svg" alt="LLM Aggregator logo" width=500>
  5    <br>
  6    <strong>Aggregate RSS feeds and summarise them with LLMs</strong>
  7</p>
  8
  9![Codeberg Release](https://img.shields.io/gitea/v/release/maxwelljensen/llm_aggregator?gitea_url=https%3A%2F%2Fcodeberg.org&style=for-the-badge)
 10![Codeberg License](assets/eupl-12-badge.svg)
 11
 12---
 13
 14## What is it?
 15
 16`llm_aggregator` fetches articles from multiple RSS/Atom feeds, filters and
 17processes the content, and sends it to any OpenAI-compatible LLM to produce a
 18concise summary, without reading dozens of posts.
 19
 20**Supports**: RSS 2.0, Atom, JSON Feed | OpenAI-compatible APIs | Local LLMs
 21(Ollama, etc.) | TUI with live progress | Text/Markdown/JSON output
 22
 23---
 24
 25## Quick start
 26
 27```bash
 28# Install
 29go install github.com/maxwelljensen/llm_aggregator/cmd/llm_aggregator.go@latest
 30
 31# Create a feeds file
 32cat > feeds.txt << 'EOF'
 33https://news.ycombinator.com/rss
 34https://lwn.net/headlines/newrss
 35EOF
 36
 37# Run
 38llm_aggregator -f feeds.txt -p "What are the top tech stories today?"
 39```
 40
 41**First run?** See [docs/USAGE.md](docs/USAGE.md) for installation, configuration,
 42and all available options.
 43
 44---
 45
 46## Key features
 47
 48| | |
 49|--|--|
 50| 🚀 | Concurrent feed fetching with rate limiting |
 51| 🔍 | Keyword filtering (include/exclude, case‑insensitive) |
 52| 📅 | Date‑based filtering and sorting (date/title/source) |
 53| 🤖 | Any OpenAI-compatible API (Deepseek, Ollama, OpenRouter, …) |
 54| 🖥️ | Interactive TUI with progress bar and mouse scrolling |
 55| 📦 | Config file, environment variables, and CLI flags |
 56| 📄 | Read feeds directly from stdin via `--stdin` |
 57| 🔧 | Dry‑run mode to validate config without API calls |
 58
 59---
 60
 61## TUI mode
 62
 63Enable the TUI with `-t` for a colourful progress bar, live article counters,
 64and elapsed time. The TUI renders LLM output as styled Markdown (headers,
 65bold, code blocks, lists) and supports keyboard navigation (j/k, arrows, b,
 66g/G) and mouse wheel scrolling.
 67
 68![LLM Aggregator action in GIF](./assets/demo.gif)
 69
 70---
 71
 72## Architecture
 73
 74```
 75Feeds file / stdin
 76        ↓
 77  ┌─────────────┐
 78  │  aggregator │   RSS/Atom/JSON Feed parsing, concurrent fetching
 79  └─────────────┘
 80        ↓
 81  ┌─────────────┐
 82  │  processor  │   Filter by keywords/age, sort, truncate
 83  └─────────────┘
 84        ↓
 85  ┌─────────────┐
 86  │     llm     │   OpenAI-compatible API call
 87  └─────────────┘
 88        ↓
 89  ┌─────────────┐
 90  │   output    │   Text / Markdown / JSON
 91  └─────────────┘
 92```
 93
 94## Configuration precedence
 95
 96```
 97CLI flags  >  Environment variables  >  Config file  >  Defaults
 98```
 99
100Create `~/.config/llm_aggregator/config.toml` (see
101[docs/USAGE.md](docs/USAGE.md#configuration) for the full reference).
102
103## Building
104
105Detailed build instructions (standard build, goreleaser, cross-compilation,
106man page installation, tests, and linting) are in
107[docs/BUILD.md](docs/BUILD.md).
108
109---
110
111## Licence
112
113This project is licensed under [European Union Public Licence
1141.2](https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12).