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

To run TrendRadar locally, clone the repository, create a Python 3.10+ virtual environment, install dependencies from requirements.txt, configure 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	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 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:

# 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

# 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

# 5. Verify environment health (optional but recommended)

python -m trendradar --doctor

# Outputs diagnostic table confirming webhook secrets and connectivity

# 6. Run the full pipeline

python -m trendradar

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

# and writes output/index.html

# 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:

./start-http.sh

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

Understanding the CLI Options

The 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 line 41
--doctor	Runs health diagnostics without fetching data	trendradar/__main__.py around line 78
--test-notification	Sends test message to all configured webhooks	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

from trendradar.__main__ import _run_doctor

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

Direct Scheduler Invocation

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

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	CLI entry point, argument parsing, pipeline orchestration
config/config.yaml	Core settings: timezone, enabled platforms, schedule presets, report mode
config/timeline.yaml	Timeline definitions: periods, day-plans, weekly schedule mapping
trendradar/context.py	Application context initialization: storage, scheduler, AI analyzer
trendradar/core/scheduler.py	Schedule resolution logic based on current time and timeline
trendradar/crawler.py	Data fetching from all enabled platforms and RSS feeds
trendradar/ai/__init__.py	AI analysis via LiteLLM integration
trendradar/notification/dispatcher.py	Multi-channel notification routing
start-http.sh	Lightweight HTTP server for report access
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 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 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 or serve via start-http.sh

The modular architecture in 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 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 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 with analysis topics. The AIAnalyzer class in 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. 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.

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 and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}