ythx-101 X Tweet Fetcher
Fetch tweets from X/Twitter without authentication. For agent-use stories, failures, and field reports, start from #22 Teahouse / 茶座.
Feature Overview
| Feature | Command | Dependencies |
|---|---|---|
| Single tweet | xtf --url <tweet_url> |
None (zero deps) |
| Reply threads | xtf --url <tweet_url> --replies |
Nitter or browser |
| User timeline | xtf --user <username> --limit 50 |
Nitter or browser |
| Search | xtf --search "<query>" |
Nitter |
| User profile | xtf --user-info <username> |
None (zero deps) |
| X List | xtf --list <list_url_or_id> |
Browser (Camofox/Playwright) |
| X Article | xtf --article <url_or_id> |
Browser (Camofox/Playwright) |
| Mentions monitor | xtf --monitor @<username> |
Nitter or browser |
python3 scripts/fetch_tweet.py accepts the same flags (v1-compatible entry point).
Basic Usage (Zero Dependencies)
# JSON output (default)
xtf --url https://x.com/user/status/1234567890
# Human-readable
xtf --url https://x.com/user/status/1234567890 --text-only
# Output covers: text, author, stats (likes/retweets/views), media URLs,
# quoted tweets, and full article text for tweet-embedded articles.
Timeline / Search / Replies (Nitter)
export XTF_NITTER=http://127.0.0.1:8788 # your instance; comma-separate for failover
xtf --user elonmusk --limit 20
xtf --search "openclaw" --limit 10
xtf --url https://x.com/user/status/123 --replies
Backend selection: --backend auto (default, Nitter first then browser), --backend nitter, --backend browser.
Lists & Articles (Browser)
# Camofox running on localhost:9377 (default), or:
export XTF_BROWSER=playwright
xtf --list https://x.com/i/lists/1455045069516357634 --limit 30
xtf --article https://x.com/i/article/2011779830157557760
Note: full X Article text requires X login; without it you get title + public preview (is_partial: true).
Mentions Monitor (cron-friendly)
xtf --monitor @yourhandle
# exit 0 = no new mentions, 1 = new mentions found, 2 = setup error
# First run builds a baseline silently; later runs report only new URLs.
Error Handling for Agents
Every error result includes error (message) and error_code:
invalid_input · not_found · rate_limited · upstream_down · backend_unavailable · all_backends_failed (with per-backend error_causes).
Python API
from xtf import Router
router = Router()
tweets = router.fetch_timeline("elonmusk", limit=20) # list[Tweet]
print(tweets[0].to_dict())
Directory Structure
src/xtf/
├── backends/ # fxtwitter.py, nitter.py, browser.py
├── parsers/ # pure parsing functions, fixture-tested
├── router.py # auto-fallback
├── monitor.py # mentions monitor
└── cli.py # the `xtf` command
scripts/fetch_tweet.py # v1-compatible shim
Looking for Chinese-platform fetching (Weibo/Bilibili/WeChat) or tweet growth tracking? Those moved out of this repo in v2 — see MIGRATION.md.