← all repositories
ythx-101/x-tweet-fetcher

Reading X without an API key, via three backends and a shrug

x-tweet-fetcher gives AI agents a read-only path into tweets, timelines, and Lists — no login, no X API, one JSON shape.

Velocity · 7d
+1.3
★ / day
star history

What it does

xtf is a Python CLI and library that fetches tweets, replies, timelines, search results, Lists, and X Articles without X credentials. It routes across three backends — FxTwitter for single tweets (pure stdlib, zero setup), Nitter for timelines and search, and a browser driver (Camofox or Playwright) for the rest — with automatic fallback between them. Everything normalizes into one Tweet/Reply/Profile/Article schema, so your agent’s prompt only ever describes one shape.

The interesting bit

The boring part is the good part: errors are machine-readable. Every failure carries an error_code (rate_limited, upstream_down, all_backends_failed, etc.) with per-backend error_causes, so an agent can actually branch on what went wrong instead of guessing at an empty result. There’s also a --ledger mode that turns any fetch into a deduped SQLite archive you can query offline later.

Key highlights

  • Single tweets work instantly with zero dependencies via FxTwitter
  • Multi-instance Nitter failover; self-hosting is recommended since public instances are flaky
  • Incremental mentions monitor with cron-friendly exit codes (0/1/2)
  • SQLite ledger dedupes by tweet_id and is schema-compatible with the OpenClaw tweet-ledger
  • Ships a SKILL.md so agents like Claude Code can drive it directly

Caveats

  • Read-only — no posting, and full X Article text needs a browser already logged in to X (otherwise you get a partial preview)
  • Not on PyPI; install is from source
  • Durability depends on FxTwitter, Nitter instances, and X’s page structure holding still — fine for agents reading on demand, not for production guarantees

Verdict

If you’re wiring an AI agent or script to read X on demand without touching credentials or paid API tiers, this is a genuinely practical tool. If you need write access or contractual reliability, pay for the official API.

Frequently asked

What is ythx-101/x-tweet-fetcher?
x-tweet-fetcher gives AI agents a read-only path into tweets, timelines, and Lists — no login, no X API, one JSON shape.
Is x-tweet-fetcher open source?
Yes — ythx-101/x-tweet-fetcher is open source, released under the MIT license.
What language is x-tweet-fetcher written in?
ythx-101/x-tweet-fetcher is primarily written in Python.
How popular is x-tweet-fetcher?
ythx-101/x-tweet-fetcher has 1k stars on GitHub.
Where can I find x-tweet-fetcher?
ythx-101/x-tweet-fetcher is on GitHub at https://github.com/ythx-101/x-tweet-fetcher.

heatdrop uses Google Analytics to see which pages get read — nothing else. Your call. How we handle data.