wyrd-tui 2.0.1

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

wyrd

A terminal RSS reader with AI-assisted discovery, for people tired of the feed.

The modern web mostly runs on other people's machines deciding what you should care about — engagement-tuned timelines, SEO-mulched listicles, ad auctions choosing which article you even see. wyrd is 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. The name is Anglo-Saxon for the woven thread of personal fate — your reading list is yours to weave.

wyrd is RSS-only on purpose: every publisher worth following exposes a feed, and the ones that don't are usually the ones you wouldn't miss. When you want something a feed won't surface, discovery asks Claude — via web search — for articles you'd like based on what you've already saved; and a deep-research agent turns Claude loose on the peer-reviewed literature when you want to actually understand a topic.

The AI features run through the claude CLI (Claude Code) rather than the Anthropic API — no API key to manage — and degrade gracefully when it isn't installed.

Features

Reader-first. Feed, Saved, and Research are each a full-width Markdown reader showing one item at a time; n / p step through, and b opens the full list (or the Research Library) on its own screen. No cramped side panes.

Feeds. RSS / Atom URLs you configure flow through one scheduler; audio and video items are filtered out — it's a reader. F5 refreshes manually; auto-refresh runs quietly on a configurable interval (hourly by default) and only speaks up when something new arrives or a source errors.

Read in-app. Opening a feed item fetches the page and renders it as clean Markdown right in the terminal — httpx → trafilatura → an in-house XML→Markdown converter that keeps code-block indentation and turns HTML tables into real pipe tables. Each article carries an N min read line and a 2–3 sentence Claude-written brief — what the piece is actually about, not the publisher's SEO blurb. Results are cached; o falls back to a real browser.

Save, tag, search. l likes a feed item into the Saved pane, where it gets editable Tags and Notes and a paragraph highlighter. FTS5-backed search spans title, body, notes, and tags. wyrd also auto-detects feeds advertised by pages you read and offers them as one-click subscriptions.

AI-assisted discovery. Claude gathers candidate articles from your recent saves and an active taste profile (built-ins: default, engineer, academic, essays — or your own). Each URL is verified, a second pass re-ranks, and the survivors land in the Feed. m on a saved item finds more like that one specifically. A one-time consent prompt explains exactly what's sent.

Deep research. Type a topic and a Claude-driven agent reads the peer-reviewed literature on it, producing a structured review paper plus a note per source — with full text where an open-access copy exists. The Research Library keeps every past run and three RAG-retrieval benchmark views; runs can fan out across several agents in parallel, and each ships a BibTeX / RIS bibliography.

Daily digest. g in the Feed has Claude summarise the last 24 hours of unread items into a themed briefing — here's what actually happened, in six bullets.

Workspaces. Independent content silos — each with its own feeds, taste profile, research output, and export. F7 cycles between them.

Obsidian export. Point [obsidian] vault at a vault and every liked article and finished research run is written there as Markdown with YAML frontmatter — direct file writes, no Obsidian app required. OPML import / export handles moving feed lists in and out.

Requirements

Python 3.12+. wyrd is developed and tested on Linux (x86_64 / arm64); macOS and Windows aren't supported targets — PRs are welcome and reviewed on their merits, but Linux changes won't be gated on cross-platform compatibility.

The AI features (briefs, discovery, digest, deep research) shell out to the claude CLI — install Claude Code and sign in. Everything else works without it.

Install

wyrd installs with uv; install uv first if you don't have it — see uv's installation guide. Then:

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

That puts a wyrd binary on your PATH (under ~/.local/bin by default). Run wyrd; the first launch opens the setup wizard — add a few RSS feeds (or let Claude suggest them), then press F5 to fetch.

To upgrade later, uv tool upgrade wyrd-tui; to remove it, uv tool uninstall wyrd-tui. Config lives at ~/.config/wyrd/config.toml and data (the SQLite database) at ~/.local/share/wyrd/wyrd.db; set WYRD_HOME=/some/dir to relocate both.

Keys

App commands work from any screen and are remappable via [keys] in config.toml; pane actions are fixed bare letters that act on whatever's in front of you.

App — Ctrl+F / Ctrl+S / Ctrl+E switch to Feed / Saved / Research · F5 refresh · F6 discovery · F2 settings · F7 cycle workspace · Ctrl+Q (or Ctrl+C) quit

In any pane — b open the list / Research Library · n / p next / previous item

Feed — l like · d dismiss · o open in browser · y copy the article · g digest. In the feed list: f cycle filter (all / interesting / ranked) · / search · s / S save and open saved searches

Saved — o open · y copy · h highlight a paragraph · H highlights list · m find more like this

Research — o / O open the file / its folder · c copy citations · Delete remove a run

The theme is set from the setup wizard (F2), with a live preview.

Contributing

Issues and pull requests are welcome at the Codeberg repository. Clone it, then:

uv sync                 # create the venv, install dependencies (incl. dev)
uv run wyrd             # launch the TUI
uv run pytest           # run the test suite (parallel via pytest-xdist; ~30s)
uv run ruff check .     # lint
uv run ruff format .    # format
uv run ty check         # type-check (src/ only)

Lint, format, and type checks should all pass clean before a change lands. PLAN.md has the design and milestone roadmap; CHANGELOG.md has the release history.

License

MIT © Blake Rhodes