KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #typescript #developer-tools #claude-code #ai-agent #codex #deepseek-harness #ai-agents #cli #react #mcp

beatcheck

★ 39 Open GitHub ↗

Opinionated TUI RSS reader for Linux and Mac

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# BeatCheck

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

Built for personal use, entirely vibe coded with [Claude Code](https://claude.ai/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+:

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

## Configuration

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

```toml
# 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 |
|----------|-------------|
| `ANTHROPIC_API_KEY` | Anthropic 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

```bash
# 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 |
| `o` | Open in browser |
| `e` | Email article |
| `b` | Bookmark to Raindrop.io |
| `Space` then `t`/`i`/`m` | Bookmark with quick tag (`twit`/`im`/`mbw`) |
| `g` | Regenerate summary |
| `d` | Delete article |
| `D` | Delete selected feed |
| `u` | Undelete last deleted |
| `?` | Show help |
| `q` | Quit |

## Systemd Timer (Auto-refresh)

To refresh feeds automatically every hour:

```bash
# 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

beatcheck

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README