# How to Run TrendRadar Locally: Complete Setup Guide for the Open-Source News Aggregator

> Learn how to run TrendRadar locally with this complete setup guide. Follow simple steps to install dependencies configure settings and run this open-source news aggregator on your machine.

- Repository: [sansan/TrendRadar](https://github.com/sansan0/TrendRadar)
- Tags: how-to-guide
- Published: 2026-04-22

---

**To run TrendRadar locally, clone the repository, create a Python 3.10+ virtual environment, install dependencies from [`requirements.txt`](https://github.com/sansan0/TrendRadar/blob/main/requirements.txt), configure [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml), and execute `python -m trendradar`.**

TrendRadar is a Python-based news-hotspot aggregator that monitors trending topics across multiple platforms and generates visual HTML reports. This guide walks you through the complete local installation process, from environment setup to troubleshooting common issues, drawing directly from the source code implementation in `sansan0/TrendRadar`.

## Prerequisites and Environment Setup

Before running TrendRadar locally, ensure your system meets these requirements:

| Component | Version | Installation |
|-----------|---------|--------------|
| **Python** | 3.10 or higher (tested on 3.11) | System package manager or python.org |
| **Dependencies** | Listed in [`requirements.txt`](https://github.com/sansan0/TrendRadar/blob/main/requirements.txt) | `pip install -r requirements.txt` |
| **(Optional) AI backend** | OpenAI, DeepSeek, or Ollama | Set `AI_API_KEY` and `AI_API_BASE` environment variables |

The repository includes helper scripts for automated setup: [`setup-mac.sh`](https://github.com/sansan0/TrendRadar/blob/main/setup-mac.sh) for macOS and `setup-windows.bat` for Windows. These create the virtual environment and install all dependencies.

## Step-by-Step Local Installation

Follow these commands to get TrendRadar running on your machine:

```bash

# 1. Clone the repository

git clone https://github.com/sansan0/TrendRadar.git
cd TrendRadar

# 2. Create and activate virtual environment

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# 3. Install dependencies

pip install -r requirements.txt

```

```bash

# 4. Configure the application

# Edit config/config.yaml to set your timezone, enable platforms, 

# and choose a schedule preset (e.g., "morning_evening")

vim config/config.yaml

```

```bash

# 5. Verify environment health (optional but recommended)

python -m trendradar --doctor

# Outputs diagnostic table confirming webhook secrets and connectivity

```

```bash

# 6. Run the full pipeline

python -m trendradar

# Collects data, optionally analyzes with AI, pushes notifications,

# and writes output/index.html

```

```bash

# 7. View the HTML report

open output/index.html        # macOS

xdg-open output/index.html    # Linux

start output\index.html       # Windows

```

For mobile testing or sharing across devices, use the bundled HTTP server:

```bash
./start-http.sh

# Prints accessible URL, e.g., http://localhost:3333/mcp

```

## Understanding the CLI Options

The [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py) file defines several command-line flags for controlling execution:

| Flag | Purpose | Implementation Location |
|------|---------|------------------------|
| `--show-schedule` | Displays the resolved schedule for current time | [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py) line 41 |
| `--doctor` | Runs health diagnostics without fetching data | [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py) around line 78 |
| `--test-notification` | Sends test message to all configured webhooks | [`trendradar/notification/dispatcher.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/notification/dispatcher.py) |

The default mode (no flags) executes the full pipeline: crawl platforms, apply AI analysis if scheduled, dispatch notifications, and generate the HTML report.

## Programmatic Usage Examples

Beyond CLI execution, you can integrate TrendRadar components directly into Python scripts:

### Running Diagnostics Programmatically

```python
from trendradar.__main__ import _run_doctor

if __name__ == "__main__":
    ok = _run_doctor()
    print("Diagnostics passed" if ok else "Problems detected")

```

### Direct Scheduler Invocation

```python
from trendradar.core.scheduler import Scheduler, ResolvedSchedule
from trendradar.core.loader import load_config
from trendradar.storage.manager import StorageManager
import datetime

# Load configuration files

cfg = load_config()
timeline = cfg["timeline"]

# Initialize SQLite storage backend

storage = StorageManager(cfg["storage"])

# Create scheduler with system clock

sched = Scheduler(
    schedule_config=cfg["schedule"],
    timeline_data=timeline,
    storage_backend=storage,
    get_time_func=datetime.datetime.now,
    fallback_report_mode=cfg["report"]["mode"],
)

# Resolve current schedule configuration

now_cfg: ResolvedSchedule = sched.resolve()
print(now_cfg)

```

### Testing Notifications via Dispatcher

```python
from trendradar.notification.dispatcher import NotificationDispatcher
from trendradar.context import AppContext

# Initialize application context

ctx = AppContext()

# Create notification dispatcher

dispatcher = NotificationDispatcher(ctx)

# Send test message to all configured channels

dispatcher.send_test_message(
    title="🚀 TrendRadar Test",
    content="If you see this, your webhook is correctly configured."
)

```

## Core Architecture and Key Files

Understanding these source files helps with customization and troubleshooting:

| File Path | Responsibility |
|-----------|--------------|
| [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py) | CLI entry point, argument parsing, pipeline orchestration |
| [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) | Core settings: timezone, enabled platforms, schedule presets, report mode |
| [`config/timeline.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/timeline.yaml) | Timeline definitions: periods, day-plans, weekly schedule mapping |
| [`trendradar/context.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/context.py) | Application context initialization: storage, scheduler, AI analyzer |
| [`trendradar/core/scheduler.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/core/scheduler.py) | Schedule resolution logic based on current time and timeline |
| [`trendradar/crawler.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/crawler.py) | Data fetching from all enabled platforms and RSS feeds |
| [`trendradar/ai/__init__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/ai/__init__.py) | AI analysis via LiteLLM integration |
| [`trendradar/notification/dispatcher.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/notification/dispatcher.py) | Multi-channel notification routing |
| [`start-http.sh`](https://github.com/sansan0/TrendRadar/blob/main/start-http.sh) | Lightweight HTTP server for report access |
| [`output/index.html`](https://github.com/sansan0/TrendRadar/blob/main/output/index.html) | Generated visual report (created at runtime) |

## Troubleshooting Common Issues

| Symptom | Root Cause | Resolution |
|---------|-----------|------------|
| "Remote version check failed" during `--doctor` | Network connectivity or proxy configuration | Set `PROXY_URL` environment variable or disable remote checks |
| No notifications received | Missing or misnamed webhook secrets | Verify exact secret names in GitHub Settings → Secrets (e.g., `FEISHU_WEBHOOK_URL`) |
| Empty HTML report | Overly restrictive [`frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/frequency_words.txt) filters | Leave file empty to include all news, or adjust keyword rules |
| "Database locked" error | Previous process holding SQLite lock | Ensure prior Python process terminated; use `--doctor` which calls `ctx.cleanup()` |

## Summary

To run TrendRadar locally:

- **Clone** the repository and create a Python 3.10+ virtual environment
- **Install** dependencies via `pip install -r requirements.txt`
- **Configure** [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) with your timezone, platforms, and schedule
- **Verify** with `python -m trendradar --doctor` before first run
- **Execute** the full pipeline with `python -m trendradar`
- **View** the generated report at [`output/index.html`](https://github.com/sansan0/TrendRadar/blob/main/output/index.html) or serve via [`start-http.sh`](https://github.com/sansan0/TrendRadar/blob/main/start-http.sh)

The modular architecture in [`trendradar/__main__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/__main__.py) allows both CLI and programmatic usage, with clear separation between configuration, scheduling, crawling, AI analysis, and notification dispatch.

## Frequently Asked Questions

### What Python version does TrendRadar require?

TrendRadar requires **Python 3.10 or higher**, with testing validated on Python 3.11. The [`setup-mac.sh`](https://github.com/sansan0/TrendRadar/blob/main/setup-mac.sh) and `setup-windows.bat` helper scripts automatically create the appropriate virtual environment.

### How do I enable AI analysis in my local TrendRadar instance?

AI analysis activates when configured in [`config/config.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/config.yaml) and triggered by the schedule or `--doctor` flag. Set `AI_API_KEY` and optionally `AI_API_BASE` environment variables, or populate [`config/ai_interests.txt`](https://github.com/sansan0/TrendRadar/blob/main/config/ai_interests.txt) with analysis topics. The `AIAnalyzer` class in [`trendradar/ai/__init__.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/ai/__init__.py) handles LiteLLM-based processing.

### Why does my HTML report show no data despite successful execution?

The most common cause is overly restrictive filtering in [`frequency_words.txt`](https://github.com/sansan0/TrendRadar/blob/main/frequency_words.txt). This file controls which keywords must appear in collected news items. Either leave the file empty to include all collected data, or adjust keyword rules to match your content sources. Verify data collection succeeded by checking console output from [`trendradar/crawler.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/crawler.py).

### Can I run TrendRadar on a schedule without keeping my computer on?

For automated scheduling without continuous local operation, deploy TrendRadar to a server or use GitHub Actions. The [`config/timeline.yaml`](https://github.com/sansan0/TrendRadar/blob/main/config/timeline.yaml) and [`trendradar/core/scheduler.py`](https://github.com/sansan0/TrendRadar/blob/main/trendradar/core/scheduler.py) components support any environment with Python and cron-like scheduling. Local execution requires your machine to remain powered during scheduled run times.