wyrd-tui 1.0.0

A TUI for personal knowledge management — feeds, saved articles, deep research, optional Obsidian export

wyrd

A small Linux reader for people tired of the feed.

The modern web is mostly other people's machines deciding what you should care about — engagement-tuned timelines, SEO-mulched listicles, ad auctions deciding which article you even see. wyrd is a terminal app built on the opposite premise: you pick the sources, you pick the keywords that matter, articles arrive as plain Markdown stripped of every banner and pop-up, and the only ranking is a transparent keyword score you control. No accounts, no recommendations from a stranger's model, no telemetry from the app itself. The name is Anglo-Saxon for the woven thread of personal fate — your reading list is yours to weave.

Built on RSS / Atom + Hacker News + Reddit — the original, syndication-driven web that still quietly works behind every "feed" — with a deep-research helper that turns Claude loose on the peer-reviewed literature when you want to actually understand something, an embedded terminal for when you don't want to leave, and optional Obsidian export so saved articles become a real local library instead of a bookmark grave on someone else's server.

Requirements: Linux (x86_64 or arm64) with Python 3.12+. wyrd uses Linux-specific behavior in the embedded terminal (pyte-backed PTY via os.forkpty). There are no plans to support macOS or Windows — Linux is the only target I'm interested in maintaining. If you want wyrd on another platform, a PR is welcome and I'll review it on its merits, but I won't be writing it myself and I won't gate Linux changes on cross-platform compatibility. See PLAN.md for the design and roadmap.

What it does

Content discovery. RSS / Atom feeds, Hacker News (top stories), and Reddit (configurable subreddits) all flow through one scheduler. Audio/video items are filtered out — it's a reader. Manual refresh with Ctrl+R; auto-refresh runs quietly on a configurable interval (default hourly) and only notifies when something new arrives or a source errors. F3 opens an Activity modal showing recent refresh runs with per-source status and any errors. Plugin auto-discovery means new sources are a single file drop in plugins/sources/.

Read in-app. Highlighting a feed item fetches the page and renders it as Markdown right in the TUI (httpx → trafilatura → in-house XML→Markdown converter that keeps code-block indentation and turns HTML tables into real GitHub pipe tables). Results are cached. No browser needed for text. o falls back to opening the URL in a real browser; y copies the URL to your clipboard (via OSC 52 — works over SSH); Enter or F4 toggles a reader-focus mode that hides the left panel.

Like → save. l in the Feed snapshots an item into the Saved pane (d dismisses it). Saved items get editable Tags and Notes alongside the article, autosaved as you navigate. FTS5-backed search (/) covers title / summary / article body / notes / tags with bm25 ranking. f in the Feed cycles between all / interesting only / ranked by keyword score — the score weights title matches × 3 and summary matches × 1 against your configured keywords.

Deep research. Press 3, type a topic, hit Enter, and a Claude-driven agent reads the peer-reviewed literature on it. Each run produces a structured review paper plus a per-source note with the agent's summary and, where an open-access copy exists, the full text (PDF or HTML, extracted to Markdown). Files land in a per-run folder; the left column is a tree of past runs with live progress while the agent works.

Embedded terminal. 4 opens a pyte-backed PTY running your $SHELL. F12 detaches; F10 (anywhere) suspends the TUI entirely and drops into a real shell — the always-works escape hatch.

Obsidian export. Set [obsidian] vault (in config.toml or via the setup wizard) and every liked article lands as Markdown under <vault>/<folder>/saved/ while every finished research run lands under <vault>/<folder>/research/. Direct file writes — no Obsidian CLI or desktop app required (Obsidian picks up new files automatically). Articles get YAML frontmatter (url, source, author, published, saved, tags including wyrd/saved). A like before extraction finishes defers the write until the worker lands. The wizard has an "Export saved items to vault" button to migrate everything you'd liked before configuring Obsidian.

Customizable. Theme picker in the setup wizard with live preview; Ctrl+T cycles themes anywhere. Every app-level key is overridable via [keys] in config.toml, applied live on save — no restart needed.

Install

uv tool install wyrd-tui    # from PyPI (binary is `wyrd`)
uv tool install .           # or from a git clone

This puts a wyrd binary on your PATH (under ~/.local/bin by default).

Develop

uv sync            # create the venv, install deps
uv run wyrd      # launch the TUI
uv run pytest      # run the tests

Config lives at ~/.config/wyrd/config.toml, data (the SQLite db) at ~/.local/share/wyrd/wyrd.db. Set WYRD_HOME=/some/dir to relocate both (used by tests).

First run pops the setup wizard — add some RSS feeds (or let Claude suggest them), then Ctrl+R to fetch.

Keys

All shortcuts are configurable — F2 opens the wizard with a "Keybindings" section, or edit [keys] in config.toml directly. Defaults:

• 1 / 2 — Feed / Saved tabs
• 4 — open the embedded terminal (a real $SHELL on a PTY)
• F12 — detach from the embedded terminal (it captures every other key while focused)
• F10 — suspend the TUI and drop into a real $SHELL (escape hatch for anything the embedded emulator mangles)
• F2 — open the setup / preferences wizard
• F3 — open the Activity modal (recent refresh runs; Esc to close)
• F4 — toggle reader focus mode: hides the left panel (feed table / saved list / research tree) so the article fills the screen; works in Feed, Saved, and Research
• ctrl+r — fetch new content from all configured feeds
• ctrl+t — cycle through Textual themes (persisted to config)
• In the Feed pane: ↑/↓ browse (the highlighted item's article is fetched and shown as Markdown on the right); Enter enters reader focus mode (article fills the pane — F4 exits); l like/save, d dismiss, o open in a browser if the in-app reader can't parse the page; y copy the article's URL to the clipboard (via OSC 52 — works over SSH); f cycles the view between all / interesting only (★) / ranked by keyword score; / focuses the search box (FTS5-backed)
• In the Saved pane: ↑/↓ browse, Enter enters reader focus mode (F4 exits), edit Tags/Notes (autosaved on navigate-away), Ctrl+S save now, y copy the article's URL, / focus search
• ctrl+q — quit (only when the terminal doesn't have focus — detach with F12 first)