BeatCheck

A terminal-based RSS reader with AI-powered article summaries.

Built for personal use, entirely vibe coded with Claude Code.

Features

• Split-pane TUI: Feed content (top) + AI bullet-point summary (bottom)
• Claude API integration: Concise bullet-point summaries of articles
• Feed discovery: Add feeds by URL with automatic RSS/Atom detection
• Raindrop.io integration: Bookmark articles with AI summary in notes
• Delete/Undelete: Remove articles with undo support
• OPML import/export: Import and export feed subscriptions
• Day-of-week display: Articles prefixed with publication day (Mon, Tue, etc.)
• Keyword filtering: Block articles by keyword (case-insensitive, word boundaries)
• SQLite caching: Offline reading with 7-day retention
• Auto-compaction: Database cleaned and vacuumed on exit
• Auto-mark read: Articles marked read after 2 seconds

Installation

From Source

Requires Rust 1.70+:

git clone https://github.com/leolaporte/beatcheck.git
cd beatcheck
cargo install --path .

Configuration

Create ~/.config/beatcheck/config.toml:

# Required for AI summaries
claude_api_key = "sk-ant-..."

# Optional: Raindrop.io integration
raindrop_token = "..."

# Optional: Custom database path (default: ~/.local/share/beatcheck/feeds.db)
# db_path = "/path/to/feeds.db"

# Optional: Refresh interval in minutes (default: 30)
# refresh_interval_minutes = 30

# Optional: Default tags for Raindrop bookmarks
# default_tags = ["rss"]

Environment Variables

Environment variables override config file values:

Variable	Description
CLAUDE_API_KEY	Claude API key for summaries
RAINDROP_TOKEN	Raindrop.io API token

Data Locations

Path	Purpose
~/.config/beatcheck/config.toml	Configuration
~/.config/beatcheck/blocklist.txt	Keyword blocklist (optional)
~/.local/share/beatcheck/feeds.db	SQLite database

Keyword Filtering

Block articles by adding keywords to ~/.config/beatcheck/blocklist.txt (one keyword per line):

bitcoin
cryptocurrency
politics

Features:

• Case-insensitive: "Bitcoin", "BITCOIN", and "bitcoin" all match
• Word boundaries: "crypto" matches "I love crypto" but NOT "cryptocurrency"
• Silent filtering: Blocked articles never appear in the UI
• Auto-reload: Blocklist reloads on each feed refresh

Articles containing any blocked keyword in their title or content are filtered during refresh before database insertion.

Usage

# Run the TUI
beatcheck

# Import OPML subscriptions
beatcheck --import feeds.opml

# Headless refresh (for cron/systemd)
beatcheck --refresh

Key Bindings

Key	Action
j/k or ↓/↑	Navigate articles
Enter	Generate/show summary
r	Refresh all feeds
a	Add new feed
i	Import OPML file
w	Export OPML file
s	Toggle starred
m	Toggle read/unread
o	Open in browser
e	Email article
b	Bookmark to Raindrop.io
f	Cycle filter (Unread/Starred/All)
g	Regenerate summary
d	Delete article
u	Undelete last deleted
?	Show help
q	Quit

Systemd Timer (Auto-refresh)

To refresh feeds automatically every hour:

# Copy service files
mkdir -p ~/.config/systemd/user
cp systemd/*.{service,timer} ~/.config/systemd/user/

# Enable timer
systemctl --user enable --now beatcheck-refresh.timer

Browser Cookie Support

BeatCheck loads browser cookies to access paywalled content from sites you're logged into.

Supported Browsers:

• Chrome/Chromium (tried first)
• Firefox (fallback)

How it works:

1. Loads cookies from browser database before fetching articles
2. Filters expired cookies automatically
3. Applies relevant cookies to each article request
4. Enables access to paywalled sites you have subscriptions to

Requirements:

• Must be logged into the site in your browser
• Browser must store persistent cookies (not incognito/private mode)

Note: Cookies are only read locally and used for article fetching. They are never uploaded or shared.

License

MIT