Metadata-Version: 2.3
Name: wyrd-tui
Version: 1.9.1
Summary: A TUI for personal knowledge management — feeds, saved articles, deep research, optional Obsidian export
Keywords: tui,textual,rss,research,terminal
Author: Blake Rhodes
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Office/Business :: News/Diary
Classifier: Topic :: Terminals
Requires-Dist: defusedxml>=0.7.1
Requires-Dist: feedparser>=6.0.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: langchain-claude-agent-sdk>=0.1.2
Requires-Dist: langgraph>=1.2.1
Requires-Dist: platformdirs>=4.9.6
Requires-Dist: pypdf>=6.11.0
Requires-Dist: textual>=8.2.5
Requires-Dist: trafilatura>=2.0.0
Requires-Python: >=3.12
Project-URL: Homepage, https://codeberg.org/brhodes/wyrd
Project-URL: Repository, https://codeberg.org/brhodes/wyrd.git
Project-URL: Issues, https://codeberg.org/brhodes/wyrd/issues
Project-URL: Changelog, https://codeberg.org/brhodes/wyrd/src/branch/main/CHANGELOG.md
Description-Content-Type: text/markdown

# 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](https://claude.com/claude-code) and sign
in. Everything else works without it.

## Install

wyrd installs with [uv](https://docs.astral.sh/uv/); install `uv` first if you
don't have it — see [uv's installation guide](https://docs.astral.sh/uv/getting-started/installation/).
Then:

```bash
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](https://codeberg.org/brhodes/wyrd). Clone it, then:

```bash
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`](PLAN.md) has the design and milestone roadmap; [`CHANGELOG.md`](CHANGELOG.md)
has the release history.

## License

[MIT](LICENSE) © Blake Rhodes
