How to configure the RSS/Atom source

This guide walks you through setting up gtdhelper to show items from RSS and Atom feeds with optional keyword filtering.

Prerequisites

uv installed (for Python venv management)

Steps

1. Create the configuration file

Create ~/.gtdhelper/rss.toml with the following content (or download the template):

[[feeds]]
name = "Rust releases"
url = "https://blog.rust-lang.org/feed.xml"

2. Add your feeds

Each [[feeds]] entry defines one RSS or Atom feed to watch. Add as many as you need:

[[feeds]]
name = "Rust releases"
url = "https://blog.rust-lang.org/feed.xml"
type = "release"

[[feeds]]
name = "NVD CVE Feed"
url = "https://nvd.nist.gov/feeds/xml/cve/misc/nvd-rss.xml"
type = "security"
include = ["CVE"]

[[feeds]]
name = "Tauri releases"
url = "https://github.com/tauri-apps/tauri/releases.atom"
type = "release"

3. Configure filters (optional)

Use include and exclude keywords to control which items appear. Keywords are matched case-insensitively against the item title and description.

[[feeds]]
name = "Rust releases"
url = "https://blog.rust-lang.org/feed.xml"
include = ["release", "stable"]    # item must match at least one keyword
exclude = ["beta", "nightly"]      # items matching any keyword are dropped

Filter evaluation order: max_age first, then exclude, then include (if non-empty).

Field	Required	Default	Description
`name`	yes	—	Human label, used as `project` in the task list
`url`	yes	—	RSS or Atom feed URL
`type`	no	`"rss"`	Task type for UI filtering (e.g. `"release"`, `"security"`)
`max_age_days`	no	`7`	Ignore items older than N days
`include`	no	`[]` (accept all)	Case-insensitive keywords, item must match at least one
`exclude`	no	`[]`	Case-insensitive keywords, item is dropped if any match

4. Verify it works

Restart gtdhelper (or wait for the next 5-minute refresh). Feed items should appear in the overlay, grouped by feed name.

Check for errors in the gtdhelper logs if nothing shows up — common causes:

Feed URL is incorrect or unreachable
All items are older than max_age_days (default 7)
include keywords are too restrictive — no items match
Feed format is not valid RSS 2.0 or Atom