name: x-tweet-fetcher description: > Fetch tweets, replies, and user timelines from X/Twitter without login or API keys. Also supports Chinese platforms (Weibo, Bilibili, CSDN, WeChat). Includes camofox_search() for zero-cost Google search without API keys. Basic tweet fetching: zero dependencies. Replies/timelines/search: requires Camofox. NEW: X-Tracker for tweet growth monitoring with burst detection. Field reports and agent-use questions are routed through Agent Waystation #22 Teahouse: https://github.com/ythx-101/openclaw-qa/discussions/22

X Tweet Fetcher

Fetch tweets from X/Twitter without authentication. Supports tweet content, reply threads, user timelines, Chinese platforms, and tweet growth tracking. For agent-use stories, failures, and field reports, start from #22 Teahouse / 茶座.

Feature Overview

Basic Usage (Zero Dependencies)

Fetch a Single Tweet

# JSON output
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456"

# Text only (human readable)
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --text-only

# Pretty JSON
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --pretty

What It Fetches

Advanced Features (Requires Camofox)

⚠️ The following features require Camofox browser service running on localhost:9377. See Camofox Setup below.

Fetch Reply Threads

# Fetch tweet + all replies (including nested replies)
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --replies

# Text-only mode with replies
python3 scripts/fetch_tweet.py --url "https://x.com/user/status/123456" --replies --text-only

Fetch User Timeline

# Fetch latest tweets from a user (supports pagination, MAX_PAGES=20)
python3 scripts/fetch_tweet.py --user <username> --limit 300

Fetch Chinese Platform Content

# Auto-detects platform from URL
python3 scripts/fetch_china.py --url "https://weibo.com/..."     # Weibo
python3 scripts/fetch_china.py --url "https://bilibili.com/..."  # Bilibili
python3 scripts/fetch_china.py --url "https://csdn.net/..."      # CSDN
python3 scripts/fetch_china.py --url "https://mp.weixin.qq.com/..." # WeChat (no Camofox needed!)

Google Search (Zero API Key)

# Python
from scripts.camofox_client import camofox_search
results = camofox_search("your search query")
# Returns: [{"title": "...", "url": "...", "snippet": "..."}, ...]

# CLI
python3 scripts/camofox_client.py "your search query"

Uses Camofox browser to search Google directly. No Brave API key needed, no cost.

Camofox Setup

What is Camofox?

Camofox is an anti-detection browser service based on Camoufox (a Firefox fork with C++ level fingerprint masking). It bypasses:

• Cloudflare bot detection
• Browser fingerprinting
• JavaScript challenges

Installation

Option 1: OpenClaw Plugin

openclaw plugins install @askjo/camofox-browser

Option 2: Manual Install

git clone https://github.com/jo-inc/camofox-browser
cd camofox-browser
npm install && npm start

Verify

curl http://localhost:9377/health
# Should return: {"status":"ok"}

REST API

# Create tab
POST http://localhost:9377/tabs
Body: {"userId":"test", "sessionKey":"test", "url":"https://example.com"}

# Get page snapshot
GET http://localhost:9377/tabs/<TAB_ID>/snapshot?userId=test

# Close tab
DELETE http://localhost:9377/tabs/<TAB_ID>?userId=test

From Agent Code

from scripts.fetch_tweet import fetch_tweet

result = fetch_tweet("https://x.com/user/status/123456")
tweet = result["tweet"]

# Regular tweet
print(tweet["text"])
print(f"Likes: {tweet['likes']}, Views: {tweet['views']}")

# X Article (long-form)
if tweet.get("is_article"):
    print(tweet["article"]["title"])
    print(tweet["article"]["full_text"])

# Links found in replies
for reply in result.get("replies", []):
    for link in reply.get("links", []):
        print(link)

Output Format

{
  "url": "https://x.com/user/status/123",
  "username": "user",
  "tweet_id": "123",
  "tweet": {
    "text": "Tweet content...",
    "author": "Display Name",
    "screen_name": "username",
    "likes": 100,
    "retweets": 50,
    "bookmarks": 25,
    "views": 10000,
    "replies_count": 30,
    "created_at": "Mon Jan 01 12:00:00 +0000 2026",
    "is_note_tweet": false,
    "is_article": true,
    "article": {
      "title": "Article Title",
      "full_text": "Complete article content...",
      "word_count": 4847
    }
  },
  "replies": [
    {
      "author": "@someone",
      "text": "Reply text...",
      "likes": 5,
      "links": ["https://github.com/..."],
      "thread_replies": [{"text": "Nested reply..."}]
    }
  ]
}

File Structure

x-tweet-fetcher/
├── SKILL.md                    # This file
├── README.md                   # GitHub page with full docs
├── scripts/
│   ├── fetch_tweet.py          # Main fetcher (tweet + replies + timeline)
│   ├── fetch_china.py          # Chinese platform fetcher
│   ├── camofox_client.py       # Camofox REST API client + camofox_search()
│   └── x-profile-analyzer.py   # User profile analysis (AI-powered)
└── CHANGELOG.md

Requirements

• Basic: Python 3.7+, no external packages, no API keys
• Advanced: Camofox running on localhost:9377
• Profile Analyzer: MiniMax M2.5 API key (for AI analysis)

X-Tracker: Tweet Growth Monitoring

Track your tweets' growth and detect viral moments — inspired by semiconductor ETCH Endpoint Detection.

Quick Start

# Add a tweet to track
python3 scripts/tweet_growth_cli.py --add "https://x.com/user/status/123" "my launch tweet"

# List all tracked tweets
python3 scripts/tweet_growth_cli.py --list

# Run sampling (new tweets <48h, every 15min)
python3 scripts/tweet_growth_cli.py --run --fast

# Run sampling (all tweets, hourly)
python3 scripts/tweet_growth_cli.py --run --normal

# Generate analysis report
python3 scripts/tweet_growth_cli.py --report 123456789

# Report with topic cross-analysis
python3 scripts/tweet_growth_cli.py --report 123456789 --cross

Cron Integration

# Dual-frequency sampling
*/15 * * * * python3 tweet_growth_cli.py --run --fast    # New tweets (<48h)
0 * * * *    python3 tweet_growth_cli.py --run --normal  # All tweets (hourly)

Detection Algorithm

Output Example

🎯 Burst detected at 2026-03-14 08:45
   - Growth rate: 156%/h
   - Composite score: +2847 (views +1200, RT +89, likes +234)
   - Propagation: 12.3 RT/1k views (influencer-driven)

How It Works

• Basic tweets: FxTwitter public API
• Replies/timelines: Camofox → Nitter (privacy-respecting X frontend)
• Chinese platforms: Camofox renders JS → extracts content
• Google search: Camofox opens Google → parses results
• X-Tracker: FxTwitter API + derivative detection + burst confirmation

🦞 x-tweet-fetcher

Fetch tweets, lists, articles, and WeChat content — with smart backend routing.

Three backends · Auto fallback · Works everywhere (VPS / Mac / Windows / CI / Claude Code / OpenClaw)

Quick Start · Backends · Capabilities · Agent Waystation · Self-hosted Nitter · Claude Code & CC

😤 Problem

You: fetch that tweet / list / article for me
AI:  I can't access X/Twitter. Please copy-paste the content manually.

You: ...seriously?

X has no free API. Scraping gets you blocked. Browser automation is fragile and won't work in headless environments.

x-tweet-fetcher solves this with smart backend routing: Nitter for zero-dependency speed, Playwright for full-feature coverage, auto fallback between them.

🔀 Three Backends

# Auto mode (default) — Nitter first, browser fallback
python3 scripts/fetch_tweet.py --user elonmusk

# Nitter only — zero dependency, no browser
python3 scripts/fetch_tweet.py --user elonmusk --backend nitter

# Browser only — full features (lists, articles)
python3 scripts/fetch_tweet.py --list 1455045069516357634 --backend browser

OpenClaw users: Playwright + Chromium are built-in. --backend auto just works — no extra install needed.

📊 Capabilities

For AI Agents: All output is structured JSON. Import as Python modules for direct integration. Exit codes are cron-friendly (0=nothing new, 1=new content).

🧭 Agent Waystation

x-tweet-fetcher is one of the field tools maintained from Agent Waystation — a stopover for AI agents, builders, tools, and field reports.

If you are building an agent that reads X/Twitter, start from the #22 Teahouse / 茶座. It is the active front desk for real usage stories, questions, failures, and agent field notes.

Bring one concrete scene:

• What does your agent observe?
• What does it remember?
• Where does it fail?
• What field tool does it still need?
• Which runtime, backend, shipped output, and evidence links would help another builder reproduce it?

From there, tool-specific bugs can move to x-tweet-fetcher issues, and broader agent workflow notes can become Waystation field reports.

Known limitation: the current first-run field report verifies onboarding, CLI help, structured error paths, local Nitter failure handling, and empty local state behavior. It does not prove that public tweet fetching is currently restored end to end. Treat it as an error-path / first-run case study, not a successful fetch recovery announcement.

中文：如果你也在养一个会看 X/Twitter 的 Agent，先来 #22 茶座 坐坐。贴链接、贴推文、贴使用场景、贴翻车现场都可以；茶座会把它分流成工具问题、field report，或者新的 agent 任务。

→ Join #22 Teahouse / 进入 #22 茶座

🚀 Quick Start

Single tweet (zero setup)

# Works immediately — no Nitter, no browser needed
python3 scripts/fetch_tweet.py --url https://x.com/elonmusk/status/123456789

Timeline, search, replies

# Set your Nitter instance URL (for nitter/auto mode)
export NITTER_URL=http://127.0.0.1:8788

# User timeline
python3 scripts/fetch_tweet.py --user elonmusk --limit 20

# Keyword search — real-time tweets
python3 scripts/nitter_client.py --search "AI agent"

# Tweet replies
python3 scripts/fetch_tweet.py --url https://x.com/elonmusk/status/123456789 --replies

# @mentions monitoring (cron-friendly)
python3 scripts/fetch_tweet.py --monitor @yourusername

# User profile analysis
python3 scripts/x-profile-analyzer.py --user elonmusk --count 100

Lists & Articles (browser backend)

# X List — requires Playwright
python3 scripts/fetch_tweet.py --list 1455045069516357634 --backend browser

# X Article
python3 scripts/fetch_tweet.py --article https://x.com/user/article/123 --backend browser

# WeChat / Weibo / Bilibili
python3 scripts/fetch_china.py --url "https://mp.weixin.qq.com/s/..."

WeChat search (always zero-dep)

python3 scripts/sogou_wechat.py --keyword "AI Agent" --limit 5 --json

🖥️ Works with Claude Code / CC

Since x-tweet-fetcher has zero mandatory dependencies, it works perfectly in constrained environments:

# In Claude Code (nitter mode, zero deps):
export NITTER_URL=http://your-vps:8788
python3 scripts/fetch_tweet.py --user YuLin807 --limit 10

# In OpenClaw (auto mode, full features):
python3 scripts/fetch_tweet.py --user YuLin807 --limit 10
# → auto-detects Nitter, falls back to Playwright if needed

🔧 Self-hosted Nitter Setup

⚠️ Public Nitter instances are dead or unreliable (as of March 2026). Self-hosting is the only reliable option.

Why you need this

Twitter removed guest API access in 2023. Public Nitter instances get rate-limited because thousands of users share a few accounts. Your own instance = your own rate limits.

5-minute setup guide

1. Install dependencies

# Ubuntu/Debian
sudo apt install -y redis-server libpcre3-dev libsass-dev

# Install Nim
curl https://nim-lang.org/choosenim/init.sh -sSf | sh
export PATH=$HOME/.nimble/bin:$PATH

2. Build Nitter

git clone https://github.com/zedeus/nitter
cd nitter
nimble build -d:release
nimble scss
cp nitter.example.conf nitter.conf

3. Get X session cookies

Use a secondary account (not your main).

1. Log into X in browser → DevTools → Application → Cookies → x.com
2. Copy auth_token and ct0
3. Create sessions.jsonl:

{"kind":"cookie","username":"myaccount","authToken":"YOUR_AUTH_TOKEN","ct0":"YOUR_CT0"}

4. Configure

[Server]
address = "127.0.0.1"  # Local only!
port = 8788

[Config]
hmacKey = "$(openssl rand -hex 32)"

[Tokens]
tokenFile = "sessions.jsonl"

5. Run & test

sudo systemctl start redis-server
./nitter

# Test
curl http://127.0.0.1:8788/YuLin807
export NITTER_URL=http://127.0.0.1:8788
python3 scripts/nitter_client.py --search "test"

Security

• Bind to 127.0.0.1 only — never expose to public internet
• Use a secondary X account — session token gives full access
• Session tokens last ~1 year

📐 How It Works

                    ┌─────────────┐
 --url              │  FxTwitter  │  ← Public API, no auth needed
                    │  (free)     │
                    └──────┬──────┘
                           │ JSON
              ┌────────────┴────────────┐
              │    --backend auto       │
              │  ┌───────┐  ┌────────┐  │       ┌──────────┐
 --user       │  │Nitter │→→│Browser │  │       │  Agent   │
 --replies    │  │(fast) │  │(full)  │  │──────▶│  (JSON)  │
 --monitor    │  │ 0 dep │  │Playwrt │  │       │          │
 --search     │  └───────┘  └────────┘  │       └──────────┘
 --list       └─────────────────────────┘
 --article
              ┌─────────────┐
 sogou_wechat │   Sogou     │  ← Direct HTTP, no API key
 fetch_china  │  (search)   │
              └─────────────┘

• Single tweets: FxTwitter — always works, zero auth
• Timeline / Replies / Search / Mentions: Self-hosted Nitter or Playwright browser
• Lists / Articles: Playwright browser (Nitter doesn't support these)
• WeChat / China platforms: Sogou search + fetch_china.py

📦 Requirements

Python 3.7+     (that's it for nitter mode)