wachi

Monitor RSS feeds and get notified on new content.

wachi monitors RSS feeds for new content and pushes notifications to 90+ services via apprise. It auto-discovers RSS feeds when available.

• Zero config for RSS -- point at a blog, wachi finds the feed
• 90+ notification services -- Slack, Discord, Telegram, email, and more
• Stateless by design -- wachi check is a one-shot command, perfect for cron
• No interactive prompts -- built for automation and AI agents

Install

# ephemeral run
npx wachi@latest --help
bunx wachi@latest --help

# persistent global install
npm i -g wachi
bun install -g wachi

# standalone binary (macOS/Linux)
curl -fsSL https://raw.githubusercontent.com/ysm-dev/wachi/main/install.sh | sh

# standalone binary (Windows PowerShell)
powershell -ExecutionPolicy Bypass -c "irm https://raw.githubusercontent.com/ysm-dev/wachi/main/install.ps1 | iex"

# homebrew
brew tap ysm-dev/tap && brew install wachi

Quick Start

# 1. Create a named channel and subscribe a URL (auto-discovers RSS)
wachi sub -n main -a "slack://xoxb-token/channel" "https://blog.example.com"

# 2. Check for new content (run this on a schedule)
wachi check

# That's it. New posts get pushed to your Slack channel.

How It Works

wachi sub -n <name> [-a <apprise-url>] <url>
      │
      ▼
  Is it RSS? ───yes───▶ Store as RSS subscription
      │no
      ▼
  Auto-discover RSS ───found───▶ Store URL + discovered feed
  (link tags, common paths)

On wachi check, item links are canonicalized and atomically admitted to a permanent per-destination delivery ledger. New links enter a durable outbox and are sent via apprise; a link already accepted for that physical destination is always skipped, even if its title, subscription, or channel name changes.

Commands

wachi sub -n <name> <url>         Subscribe a URL to a named channel
  -a, --apprise-url <url>         Required when creating a new channel
  -e, --send-existing             Send all current items on next check (skip baseline)

wachi unsub -n <name> [url]       Unsubscribe a URL or remove entire channel

wachi ls                          List all channels and subscriptions

wachi check                       Check all subscriptions for changes
  -n, --name <name>               Check specific channel only
  -p, --concurrency <number>      Max concurrent checks (default: 10)
  -d, --dry-run                   Preview without sending or recording

wachi test -n <name>              Send a test notification

wachi upgrade                     Update a persistent wachi install

wachi upgrade follows the original install method:

• npm global -> npm install -g wachi@latest
• bun global -> bun install -g wachi@latest
• Homebrew -> brew upgrade wachi
• standalone binary -> downloads the latest GitHub Release and replaces the current binary

Ephemeral runs via npx and bunx are not persistent installs, so they are not upgraded in place. Re-run them with @latest instead.

Global flags: --json / -j for machine-readable output, --verbose / -V for detailed logs, --config / -C for custom config path.

Examples

# Blog (auto-discovers RSS)
wachi sub -n main -a "slack://xoxb-token/channel" "https://blog.example.com"

# GitHub releases RSS feed
wachi sub -n alerts -a "discord://webhook-id/token" "https://github.com/ysm-dev/wachi/releases.atom"

# Add another subscription to an existing channel name
wachi sub -n main "https://example.com/changelog"

# YouTube channel
wachi sub -n media -a "tgram://bot-token/chat-id" "https://youtube.com/@channel"

# URL without https:// (auto-prepended)
wachi sub -n main "blog.example.com"

# Send all existing items on next check (no baseline)
wachi sub -n alerts -e "https://github.com/ysm-dev/wachi/releases.atom"

# Dry-run: see what would be sent
wachi check -d

# Check specific channel only
wachi check -n main

# Run every 5 minutes with crnd
crnd "*/5 * * * *" wachi check

# System cron
crontab -e
# */5 * * * * wachi check

Notifications

wachi uses apprise for delivery -- Slack, Discord, Telegram, Email, Pushover, Gotify, ntfy, and 90+ more.

Each new item is sent as a separate message:

https://blog.example.com/post/new-feature

New Feature: Faster Builds with Incremental Compilation

Test a saved channel anytime:

wachi test -n main

Configuration

Config lives at ~/.config/wachi/config.yml (XDG-compliant, default). Auto-created on first wachi sub.

wachi reads config in this order: config.yml -> config.jsonc -> config.json.

# Channels and subscriptions (managed by wachi sub/unsub)
channels:
  - name: "main"
    apprise_url: "slack://xoxb-token/channel"
    subscriptions:
      - url: "https://blog.example.com"
        rss_url: "https://blog.example.com/feed.xml"

Each channel entry requires name. Names must be unique (case-insensitive). The same RSS feed cannot be configured more than once for the same physical notification destination.

All fields are optional with sensible defaults. An empty config file is valid.

| Variable | Purpose | |----------|---------| | WACHI_APPRISE_URL | Override notification destination for ALL channels | | WACHI_ARCHIVE_ACCESS_KEY | Optional Internet Archive access key for authenticated Wayback submissions | | WACHI_ARCHIVE_SECRET_KEY | Optional Internet Archive secret key for authenticated Wayback submissions | | WACHI_CONFIG_PATH | Custom config file path | | WACHI_DB_PATH | Custom database path | | WACHI_NO_ARCHIVE | Set to 1 to disable auto-archiving of notified URLs | | WACHI_NO_AUTO_UPDATE | Set to 1 to disable auto-update |

Notified item URLs are archived to the Wayback Machine by default. If archive keys are unset, wachi falls back to the anonymous save endpoint. Set both archive keys for authenticated POST submissions and higher Wayback limits.

For x.com / twitter.com items, wachi archives the transformed notification URL (for example fixupx.com) because Wayback currently blocks direct archiving of the original X URL.

Design

• Stateless checks -- wachi check is a one-shot command. Bring your own scheduler (cron, crnd, systemd, launchd)
• Permanent link identity -- compact binary keys track each canonical link once per physical destination and are never expired
• Durable outbox -- items are admitted transactionally before delivery, so feed changes and process restarts cannot lose queued work
• Conservative retries -- pre-dispatch failures retry; ambiguous post-dispatch failures are retained as uncertain to prevent duplicates
• Baseline seeding -- older current items are seeded and the latest item is sent once; --send-existing defers every current item to the next check
• SQLite WAL mode -- composite constraints and delivery leases coordinate concurrent checks
• No interactive prompts -- ever. Errors tell you exactly what to set and where (What / Why / Fix pattern)
• Atomic config writes -- write to temp, then rename. No corruption from concurrent access
• JSON envelope -- --json on all commands returns {"ok": true, "data": {...}} or {"ok": false, "error": {"what", "why", "fix"}}

Development

bun install
bun run src/index.ts --help

# Quality checks
bun run lint          # Biome v2
bun run typecheck     # tsgo
bun test              # Bun test runner
bun run knip          # Dead code detection

# Database migrations
bun run db:generate

Tech Stack

| Component | Choice | |-----------|--------| | Runtime | Bun (bun:sqlite, bun build --compile) | | Type checker | tsgo (@typescript/native-preview) | | CLI | citty | | Database | drizzle-orm + bun:sqlite | | HTTP | ofetch | | RSS | rss-parser | | Notifications | apprise via uvx | | Linter | Biome v2 |

License

MIT