bahdotsh · bahdotsh · May 13, 2026 · May 7, 2026 · May 11, 2026 · May 11, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Feedr is a terminal-based RSS/Atom feed reader built with Rust, using ratatui/crossterm for the TUI. It supports feed management, categorization, filtering, dual themes, OPML import, auto-refresh with per-domain rate limiting, feed auto-discovery from HTML pages, configurable keybindings, mouse support, and a help overlay.
+Feedr is a terminal-based RSS/Atom feed reader built with Rust, using ratatui/crossterm for the TUI. It supports feed management, categorization, filtering, dual themes, OPML import, auto-refresh with per-domain rate limiting, feed auto-discovery from HTML pages, configurable keybindings, mouse support, a help overlay, and newsboat-style external-command hooks (macros and `exec_on_new`).
 
 ## Build & Development Commands
 
@@ -28,11 +28,11 @@ MSRV: 1.75.0. CI runs tests on stable, beta, and 1.75.0.
 ### Core modules
 
 - **`app.rs`** — `App` struct holding all application state. All state mutations (feed ops, filtering, categorization, persistence) happen through its methods. This is the largest and most central file.
-- **`tui.rs`** — Terminal setup/teardown, main event loop (`run_app`), and feed refresh logic.
-- **`events.rs`** — All keyboard and mouse event handling (`handle_events`). Input dispatches based on `View` × `InputMode` enums. Separated from `tui.rs` for maintainability.
-- **`keybindings.rs`** — `KeyAction` enum, default keybinding map, key string parsing, and config-driven keybinding overrides via `[keybindings]` TOML section.
+- **`tui.rs`** — Terminal setup/teardown, main event loop (`run_app`), feed refresh logic, and external-command runners (`suspend_for_command`, `spawn_detached`, `drain_macro_steps`, `collect_exec_on_new`/`flush_exec_on_new`). `TerminalRestoreGuard` (RAII) re-enters alt-screen + raw mode + mouse capture on drop so a panic in a child invocation can't leave the terminal broken.
+- **`events.rs`** — All keyboard and mouse event handling (`handle_events`). Input dispatches based on `View` × `InputMode` enums. Hosts the macro engine (`dispatch_action`, `run_macro`, `build_pipe_invocation`, `build_exec_invocation`). Separated from `tui.rs` for maintainability.
+- **`keybindings.rs`** — `KeyAction` enum, default keybinding map, key string parsing, config-driven keybinding overrides via `[keybindings]` TOML section, and newsboat-style macro parsing (`MacroStep`, `MacroBinding`, `MacroOptions`, `parse_macro_string`).
 - **`feed.rs`** — Data models (`Feed`, `FeedItem`, `FeedCategory`), RSS/Atom parsing via `feed-rs`, and HTML feed auto-discovery via `scraper`.
-- **`config.rs`** — XDG-compliant config loading/saving (`~/.config/feedr/config.toml`). Includes `keybindings: HashMap<String, toml::Value>` for custom key overrides. Auto-generates defaults on first run.
+- **`config.rs`** — XDG-compliant config loading/saving (`~/.config/feedr/config.toml`). Includes `keybindings: HashMap<String, toml::Value>` for custom key overrides, `[hooks]` (`exec_on_new`), `[macros]`, and `[macro_options]`. Auto-generates defaults on first run.
 - **`config_cli.rs`** — CLI subcommand handler for `feedr config list/get/set`.
 - **`config_tui.rs`** — Interactive TUI config editor (`feedr config --tui`).
 - **`config_ui.rs`** — Rendering for the TUI config editor.
@@ -64,11 +64,13 @@ MSRV: 1.75.0. CI runs tests on stable, beta, and 1.75.0.
 - **Rate limiting**: `last_domain_fetch: HashMap` throttles per-domain HTTP requests.
 - **Authenticated feeds**: `feed_headers: HashMap<String, HashMap<String, String>>` in `App` maps feed URLs to custom HTTP headers. Built from `config.default_feeds` entries that have `headers`. Passed to `Feed::fetch_url()` at all fetch call sites.
 - **Compact mode**: `app.compact` bool is updated each frame by `update_compact_mode(terminal_height)`. Rendering in `ui.rs` branches on `app.compact` for layout, title bar, help bar, and dashboard item format. Controlled by `config.ui.compact_mode` (`Auto`/`Always`/`Never`). Dialog modals use `centered_rect_with_min()` to enforce minimum dimensions regardless of compact mode.
+- **External-command hooks (macros + `exec_on_new`)**: Commands are run **without a shell**. Templates are tokenized once at config load via `shlex`, then `expand_argv_template` substitutes `%X` placeholders into individual argv tokens (no re-expansion), so feed content cannot break out of an argument. The macro engine queues steps into `app.pending_macro_steps` from `events.rs` and the TUI loop drains them in `tui.rs::drain_macro_steps` — drain lives at the loop level because `pipe-to` needs the terminal handle to suspend the TUI. Chains halt on the first step error (tracked via a `pre_error` guard so a stale `app.error` doesn't spuriously abort). The macro prefix (default `,`) is checked at the top of `handle_key_event` and only when `input_mode == Normal`, so text-input modes are not disturbed; an idle prefix times out via the existing success-message timeout.
+- **`exec_on_new` crash semantics**: AT-MOST-ONCE. `flush_exec_on_new` persists the `seen_items` / `feeds_seeded` sets *before* spawning any child, so a kill mid-fire loses a notification rather than re-firing on the next launch. `mark_feed_seen` only flips `feeds_seeded` on a fetch that returned items (transiently-empty first fetches don't seed), and the first observation of a feed seeds the seen-set silently to avoid a firehose. Children are spawned detached with stdio nulled; a reaper thread waits on each so they don't linger as zombies. The seen-set is pruned in `remove_current_feed` to prevent monotonic growth across feed churn.
 
 ## Commit Conventions
 
 Uses **conventional commits** — `feat:`, `fix:`, `refactor:`, `docs:`, `perf:`, `test:`, `chore:`, `build:`, `style:`. Changelog is generated by git-cliff (`cliff.toml`).
 
 ## Testing
 
-Integration tests live in `/tests/integration_test.rs` and test feed parsing against real URLs. Unit tests are inline in `config.rs`, `app.rs`, and `keybindings.rs`.
+Integration tests live in `/tests/integration_test.rs` and test feed parsing against real URLs. Unit tests are inline in `config.rs`, `app.rs`, `keybindings.rs`, `events.rs`, and `tui.rs` (the macro-drain tests use a `TestBackend` to avoid needing a real TTY).
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -33,6 +33,7 @@ opml = "1.1.6"
 toml = "0.8"
 scraper = "0.18"
 url = "2"
+shlex = "1.3"
 
 [profile.release]
 codegen-units = 1

diff --git a/README.md b/README.md
@@ -36,6 +36,7 @@ Feedr is a feature-rich terminal-based RSS feed reader written in Rust. It provi
 - **Compact Mode**: Automatic compact layout for small terminals (≤30 rows), with manual `always`/`never` override in config
 - **CLI Config Management**: Get, set, and list configuration from the command line (`feedr config`), or use the interactive TUI config editor (`feedr config --tui`)
 - **Configurable Keybindings**: Remap any key action via the `[keybindings]` section in `config.toml`
+- **External-Command Hooks**: Newsboat-style macros (`pipe-to`, `exec`) bound to keys, plus `exec_on_new` notifications fired per new item — all with shell-free argument templating
 - **Configurable**: Customize timeouts, themes, UI behavior, and default feeds via TOML config
 - **XDG Compliant**: Follows standard directory specifications for configuration and data storage
 
@@ -313,6 +314,66 @@ Cookie = "session=abc123"
 ```
 Headers are sent with every request for that feed, including refreshes.
 
+### External-Command Hooks
+
+Feedr supports newsboat-style external commands for two workflows: **macros** (key-triggered chains that act on the focused article) and **`exec_on_new`** (a notification hook fired per newly-seen item after each refresh).
+
+**Commands are not run through a shell.** Templates are tokenized once at config load, and `%X` placeholders are substituted into individual `argv` tokens — feed content can never break out of an argument. For pipes, redirection, or globbing, write a small shell script and invoke that.
+
+#### Template Variables
+
+Expanded in every `argv` token of macro and hook commands:
+
+| Variable | Expands to |
+|----------|------------|
+| `%t` | Article title |
+| `%u` | Article URL |
+| `%a` | Author |
+| `%d` | Formatted publish date |
+| `%f` | Feed title |
+| `%F` | Feed URL |
+| `%%` | Literal `%` |
+
+#### Macros
+
+A macro binds a key to an ordered chain of steps. Trigger with `<prefix><key>` (default prefix is `,`). Steps are separated by `;`. An optional trailing ` -- "description"` overrides the help-overlay label.
+
+```toml
+[macros]
+y = 'open-in-browser ; pipe-to "yt-dlp %u"'
+w = 'pipe-to "wallabag-cli add %u" -- "Save to Wallabag"'
+n = 'pipe-to "tee /tmp/out.txt" stdin=metadata'
+
+[macro_options]
+prefix = ","                  # the macro-prefix key
+pipe_default_stdin = "body"   # body | title | url | metadata | none
+```
+
+**Step kinds:**
+- `<action>` — invoke a built-in action. Supported in macros: `open-in-browser`, `toggle-star`, `toggle-read`, `mark-all-read`, `refresh`, `toggle-theme`, `extract-links`, `help`.
+- `pipe-to "cmd %u" [stdin=…]` — suspend the TUI, run the command, and pipe article content to its stdin. `stdin` is one of `body` (default), `title`, `url`, `metadata`, or `none`.
+- `exec "cmd %u"` — spawn the command detached (no stdin, no terminal takeover).
+
+Chains halt on the first step error. Press `Esc` after the prefix to cancel; an unbound follow-up surfaces a "No macro bound" error. Macros are also rendered in the help overlay (`?`).
+
+#### `exec_on_new` Notifications
+
+Fire a command once per newly-seen item after each refresh. The first successful fetch of each feed seeds the seen-set silently — you do **not** get a firehose on initial load or first run.
+
+```toml
+[hooks]
+exec_on_new = 'notify-send "New: %t" "%f"'
+```
+
+Children are spawned **detached** so the TUI never blocks on them. Crash semantics are **at-most-once**: feedr persists the seen-set before spawning, so a kill mid-fire loses a notification rather than re-firing on the next launch. Prefer idempotent commands (e.g. `wallabag-cli add` is safe; `mail-me` is not).
+
+#### Security Notes
+
+- The shell is never invoked, so feed content in `%t` / `%a` / etc. cannot escape an argument.
+- **Do not wrap your command in `sh -c "... %t ..."`** — that reintroduces shell injection through item titles. Write a script file and invoke it instead.
+- `~` / `$HOME` / `$VAR` are **not** expanded — use absolute paths.
+- If a macro's command template has unbalanced quotes or names an unknown action, feedr surfaces a startup warning rather than failing silently at trigger time.
+
 ### Configurable Keybindings
 
 Remap any action by adding a `[keybindings]` section to your config file. Each action can be bound to a single key string or an array of keys: