Hys

Hys — RSS Reader for Digital Minimalists

Features • Quick Start • Installation • Usage • Configuration • Contributing • License

Hys is a fast, lightweight, and opinionated terminal RSS reader written in Zig that helps you avoid doom-scrolling. It enforces a once-per-day fetch limit, encouraging you to gather new information in a single daily batch like a morning newspaper, rather than receive an endless stream of pings and notifications throughout the day.

✨ Features

🚀 Quick Start (macOS/Linux)

Homebrew

brew install superstarryeyes/tap/hys

Arch Linux (AUR)

yay -S hys          # Latest release
yay -S hys-git      # Latest development version

Add your first feed and start reading:

hys --sub "https://news.ycombinator.com/rss"
hys

📦 Installation (macOS/Linux/Windows)

Prerequisites

• Zig 0.16.0: For building from source. Install instructions
• libcurl: Robust HTTP/2 and TLS support. Install via your package manager:
  • macOS: Pre-installed (no action needed)
  • Ubuntu/Debian: sudo apt-get install libcurl4-openssl-dev
  • Fedora: sudo dnf install libcurl-devel
  • Arch: sudo pacman -S curl
  • Windows: choco install curl (using Chocolatey) or vcpkg install curl:x64-windows

Build from Source

1. Clone the repository:

   git clone https://github.com/superstarryeyes/hys.git
   cd hys
   

2. Build and Install:

   # Install to ~/.local/bin (make sure it's in your PATH)
   zig build -Doptimize=ReleaseSafe install -p ~/.local
   

💻 Usage

Reading Feeds

# Add a feed to your main group
hys --sub "https://site.com/feed"

# Add a feed to a specific group
hys tech --sub "https://site.com/feed"

# Read the main group
hys

# Read a specific group
hys tech

# Read multiple groups combined
hys tech,science,art

# Read all groups at once
hys --all

# One-off read of a URL (doesn't save to config)
hys https://example.com/rss.xml

Manage Feeds and Groups

Daily Flow and History

Config and Pager

Navigation (Pager Mode)

When Hys opens in your system pager (less), these keys are available:

• Line-by-line

  • j or Down: Scroll down one line
  • k or Up: Scroll up one line
  • Enter: Scroll down one line
  • y: Scroll up one line

• Paging

  • Space or f or PageDown: Page down one screen
  • b or PageUp: Page up one screen
  • d: Half-page down
  • u: Half-page up

• Jumps

  • g: Jump to top
  • G: Jump to bottom

• Search

  • /text: Search forward
  • ?text: Search backward
  • n: Next match
  • N: Previous match

• Misc

  • h: Show help for all less commands
  • q: Exit back to terminal

⚙️ Configuration

Hys creates a JSON configuration file at ~/.hys/config.json on first run.

{
  "display": {
    "maxTitleLength": 120,
    "maxDescriptionLength": 300,
    "maxItemsPerFeed": 20,
    "showPublishDate": true,
    "showDescription": true,
    "showLink": true,
    "truncateUrls": true,
    "pagerMode": true,
    "underlineUrls": true,
    "dateFormat": "%Y-%m-%d"
  },
  "history": {
    "retentionDays": 50,
    "fetchIntervalDays": 1,
    "dayStartHour": 0
  },
  "network": {
    "maxFeedSizeMB": 0.2
  }
}

[!NOTE] Apple's default Terminal does not support OSC 8 hyperlinks. If you're using Apple Terminal, you need to set truncateUrls to false in your config. For a better experience, consider using a terminal that supports OSC 8 hyperlinks, such as Ghostty, Wezterm, Kitty, or iTerm2.

Managing Feeds

Feeds are stored in JSON files within ~/.hys/feeds/. Each group has its own file corresponding to its name (e.g., main is stored in ~/.hys/feeds/main.json).

To remove or edit a feed:

1. Open the group's JSON file (e.g., ~/.hys/feeds/main.json).
2. Locate the feed object within the feeds array.
3. Delete the object to unsubscribe, or edit fields like xmlUrl or text.
4. Save the file.

🛠️ Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Join our Discord community for discussions, support and collaboration.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.