Twitter/X — site-use skill

Scope

Only use site-use commands listed below. Do not use puppeteer, chrome-devtools-mcp, or any other browser automation tool directly.

First-time setup

When the user asks to set up site-use or you get a BrowserNotRunning error on first use:

Run site-use browser launch to start Chrome
Tell the user to log in to Twitter in the Chrome window that opened
Wait for the user to confirm they've logged in
Run site-use twitter check-login to verify
If logged in, run site-use twitter feed --count 10 --fields author,text,url to collect the first batch

The launched Chrome uses an isolated profile — the user's regular browser data is never exposed.

When to use which command

| Need | Command | |------|---------| | Latest timeline | site-use twitter feed | | Search Twitter | site-use twitter search | | Specific tweet + replies | site-use twitter tweet_detail | | Query cached data | site-use search |

Intent Freshness

Determine whether to fetch fresh data or use cache based on the user's intent.

| Freshness | Signal | Example intents | Strategy | |-----------|--------|-----------------|----------| | High | User explicitly asks for "now/today/latest/trending/breaking" | "what's trending", "latest news on X" | Always --fetch | | Medium | No explicit time, but topic is time-sensitive | "any updates on Claude Code", "what happened with the outage" | Prefer --fetch | | Low | Retrospective or analysis, references past time | "analyze last week's AI discussions", "what did we collect yesterday" | --local or default cache |

Default: When freshness is ambiguous, prefer fetch. The cost of missing breaking news outweighs an extra fetch.

Commands

twitter feed

Collect tweets from the home timeline. Results are auto-stored in the local knowledge base.

site-use twitter feed [options]
  --count <n>          Number of tweets, 1-100 (default: 20)
  --tab <name>         following | for_you (default: for_you)
  --local              Force local cache query (no browser)
  --fetch              Force fetch from browser (skip freshness check)
  --max-age <minutes>  Max cache age before auto-fetching (default: 120)
  --fields <list>      Comma-separated: author,text,url,timestamp,links,mentions,media
  --quiet, -q          Suppress JSON output, show one-line summary only
  --debug              Include diagnostic trace

for_you — algorithmic feed, personalized recommendations
following — chronological, only accounts the user follows

Just run twitter feed directly — the framework auto-checks login. If the user isn't logged in, you'll get a SessionExpired error with a clear hint.

twitter search

Search tweets on Twitter. Supports Twitter search operators.

site-use twitter search [options]
  --query <text>       Search query (required, supports Twitter operators)
  --tab <name>         top | latest (default: top)
  --count <n>          Number of tweets, 1-100 (default: 20)
  --fields <list>      Comma-separated: author,text,url,timestamp,links,mentions,media
  --quiet, -q          Suppress JSON output, show one-line summary only
  --debug              Include diagnostic trace

twitter tweet_detail

Get a specific tweet and its replies.

site-use twitter tweet_detail [options]
  --url <url>          Tweet URL (required)
  --count <n>          Max replies, 1-100 (default: 20)
  --fields <list>      Comma-separated: author,text,url,timestamp,links,mentions,media
  --quiet, -q          Suppress JSON output, show one-line summary only
  --debug              Include diagnostic trace

Returns JSON with items[0] as the anchor tweet, items[1..n] as replies. Each reply has siteMeta.inReplyTo for threading. Quoted tweets are nested under siteMeta.quotedTweet.

twitter check-login

site-use twitter check-login

No options. Returns { loggedIn: boolean }. Reserve for when the user explicitly asks about login status — twitter feed auto-checks login already.

search (local knowledge base)

Query the local knowledge base. Does NOT fetch new data.

site-use search [query] [options]

Filters:
  --author <name>         Filter by author (@ prefix optional)
  --start-date <date>     Start date (local time, flexible format)
  --end-date <date>       End date (local time, flexible format)
  --hashtag <tag>         Filter by hashtag
  --mention <handle>      Filter by mentioned handle (@ prefix optional)
  --surface-reason <r>    original | retweet | quote | reply
  --min-likes <n>         Minimum likes
  --min-retweets <n>      Minimum retweets

Output:
  --max-results <n>       Max results (default: 20)
  --fields <list>         Comma-separated: author,text,url,timestamp,links,mentions,media

Browser management

site-use browser launch     # Launch Chrome (detached)
site-use browser status     # Show connection status
site-use browser close      # Kill Chrome and clean up

Screenshots

site-use screenshot --site twitter
# Returns: {"screenshot": "~/.site-use/screenshots/twitter.png"}

Then use the Read tool to view the image file.

Stats

site-use stats              # Show storage statistics

Smart Cache

twitter feed has smart caching (default 120 min):

| Flag | Behavior | |------|----------| | (none) | Check cache freshness; fetch if stale (> --max-age) | | --local | Force local cache only — no browser needed | | --fetch | Force fresh fetch — skip freshness check | | --max-age <min> | Custom staleness threshold (default: 120) |

Error Recovery

| Error | Action | |-------|--------| | SessionExpired | Ask the user to log in manually in Chrome, then retry | | RateLimited | Stop ALL twitter commands. Wait 15+ min. Use search for cached data meanwhile | | BrowserDisconnected | Run site-use browser launch, then retry | | BrowserNotRunning | Run site-use browser launch first | | ElementNotFound | Page may still be loading. Wait a few seconds, retry |

Rate limiting deserves extra care

Do not retry immediately. Wait for the reset time shown in the error.
Do not run any twitter commands during cooldown — this can extend the limit.
Switch to offline work — use search to analyze cached data.
If "account suspended" appears, alert the user — this is a policy issue, not a quota issue.

Examples

Daily hot topics briefing (High freshness)

# 1. Fetch fresh timeline
site-use twitter feed --fetch --count 50 --tab for_you --fields author,text,url

# 2. Filter high-engagement posts from cache
site-use search --start-date "today" --min-likes 100 --fields author,text,url

User says "what's hot today" → freshness is high, always fetch first, then filter.

Breaking news search (High freshness)

site-use twitter search --query "Claude Code" --count 30 --fields author,text,url

Topic is actively unfolding → always fetch. Do NOT rely on cache for breaking events.

Retrospective analysis (Low freshness)

# Pure cache query, no browser needed
site-use search "AI agent" --start-date "2026-03-24" --end-date "2026-03-28" --min-likes 50 --fields author,text,url

# Or explicitly local
site-use twitter feed --local --tab for_you --fields author,text,url

User asks about past data → use cache. No reason to fetch.

Time Convention

All timestamps are local timezone ISO 8601 (e.g. 2026-03-29T10:03:00+08:00). Date filters (--start-date, --end-date) accept flexible local formats — "2026-03-29", "yesterday", "2026-03-29 10:00" all work.

When the user doesn't specify a time range, default to the last 24 hours.

Tips

Always use --fields to control output size. Output exceeding ~30KB gets truncated to a temp file. Always pass --fields author,text,url (or whichever fields needed) to keep output compact.
Prefer search over re-fetching. If tweets were collected recently, search the cache instead. Saves time and avoids rate limits.
Use --local for offline analysis. When the browser isn't running or you want speed, --local reads from cache without touching the browser.
Use --debug when troubleshooting. Adds diagnostic trace. On errors, trace is always included regardless of --debug.
Short search queries are slow. Full-text search needs 3+ characters. Shorter queries fall back to a full table scan.
Combine filters for precision. search "AI" --min-likes 500 --start-date "yesterday" is more useful than a broad search.