runesleo/x-reader

What is x‑reader?

x‑reader is a Python‑based Agent Skill and command‑line tool that fetches the actual content behind a URL – not just the preview that a search engine or social‑media platform shows. It works with many online sources (X/Twitter, YouTube, podcasts, WeChat, RSS, etc.) and tells an AI agent whether the full source was read, only partially read, or could not be fetched.

How it works

1. URL → platform‑specific fetcher – each supported site has a small module (e.g., twitter.py, youtube.py) that knows how to retrieve the canonical source: the tweet text via oEmbed, a YouTube transcript via yt‑dlp, a Bilibili subtitle, etc.
2. Evidence contract – after a fetch the tool returns one of four statuses:
   • PASS – everything needed for the answer was read.
   • PARTIAL – some media layer (video, audio, subtitles) is missing.
   • FAIL – the page could not be fetched reliably.
   • UNKNOWN – the retrieved material is ambiguous.
3. CLI / JSON output – x-reader <url> prints a short human‑readable summary; adding --json gives a machine‑readable payload that an AI agent can consume.
4. Optional MCP server – a lightweight HTTP server (mcp_server.py) exposes the same functions (read_url, detect_platform, …) so agents like Claude Code can call the tool remotely.

Why “source‑first” matters

Agents often answer a question by quoting a search snippet or a tweet’s caption, which may omit crucial media (videos, subtitles, pay‑walled text). x‑reader makes the gap explicit, preventing hallucinations and letting the user know exactly what evidence is available.

Main features (as described in the README)

Feature	Description
Multi‑platform support	X/Twitter, YouTube, Bilibili, WeChat, Xiaohongshu, Telegram, RSS, generic web articles, Apple Podcasts, etc.
Media handling	Retrieves attached videos, subtitles, and can transcribe audio with Groq Whisper (whisper‑large‑v3).
CLI	x-reader <url> for quick checks; x-reader doctor for a self‑test; --json for structured output.
Agent Skill	Installable via npx skills add runesleo/x-reader --skill x-reader; the skill can be listed without installing.
MCP server	Optional FastMCP‑compatible server for remote calls (x-reader-mcp).
Security model	Treats all fetched data as untrusted, never executes it, and isolates cookies unless explicitly opted‑in.
Extensible Python library	UniversalReader class for programmatic use (await reader.read(url)).
Evidence contract	Explicit PASS / PARTIAL / FAIL / UNKNOWN statuses for each fetch.

Who might use it?

• AI‑agent developers who need a reliable way to prove that a model actually consulted the original source before answering.
• Researchers building retrieval‑augmented generation pipelines that must track which media layers were consumed.
• Power users who want a CLI to download and verify the full content of a tweet, video, or article.

Installation snapshot

# Install the CLI directly from the repo
pip install "x-reader @ git+https://github.com/runesleo/x-reader.git"
# Optional browser fallback (Playwright) and media tools
pip install "x-reader[browser] @ git+https://github.com/runesleo/x-reader.git"
playwright install chromium

License

MIT – free for personal and commercial use.

---

All details above are taken directly from the repository’s README; no additional features are inferred.