Twitter Intel: Keyword Search & Trend Monitor

search twitter by keyword, collect high-engagement tweets, analyze trends over time, and generate structured reports. powered by graphql search with no browser automation needed. use this when you need real-time keyword intelligence, competitive monitoring, or historical trend analysis from twitter/x.

---

intent

this skill searches twitter/x by keyword, filters tweets by engagement metrics, monitors keywords over time with state persistence, and generates trend analyses from accumulated data. use it for competitive intelligence, brand monitoring, breaking topic tracking, or analyzing how conversations shift week-over-week around specific keywords or phrases.

---

inputs

external connections:

• twitter/x graphql api (via graphql endpoint)
• local cookie-based auth (no oauth, manual refresh required)

required files and env vars:

• TWITTER_COOKIES_PATH env var pointing to location of twitter_cookies.json
• twitter_cookies.json file with format: [{"name": "auth_token", "value": "..."}, {"name": "ct0", "value": "..."}]
  • extract via chrome devtools: application tab > cookies > x.com
  • cookies expire every ~2 weeks, will return 403 when stale
• rnet_twitter.py (async graphql client, get from https://github.com/PHY041/rnet-twitter-client)
• rnet>=3.0.0rc20 python package (rust http client with tls fingerprint emulation)

optional config files (for monitoring workflows):

• twitter-monitors.json defining keywords, filters, alert thresholds, and schedules
• twitter-monitors-state.json tracking last run times and tweet ids seen

parameters passed by user:

• query string (keyword, phrase, or twitter operators)
• count (number of tweets to fetch, default 200)
• product mode ("Top" for high-engagement or "Latest" for real-time)
• date range (since/until parameters optional)
• min_likes threshold for filtering (optional)

---

procedure

phase 1: on-demand search

step 1: load client and authenticate

• input: TWITTER_COOKIES_PATH env var, twitter_cookies.json file location
• instantiate RnetTwitterClient()
• call client.load_cookies(cookies_path) to load auth cookies
• output: authenticated client ready for graphql queries
• edge case: if cookies file missing or path undefined, raise FileNotFoundError with guidance to set env var and extract fresh cookies

step 2: execute search query

• input: query string (e.g. "OpenAI lang:en"), product mode ("Top" or "Latest"), count (default 200)
• call await client.search_tweets(query=query, count=count, product=product)
• output: list of tweet objects with fields: text, author, favorite_count, retweet_count, view_count, is_reply, created_at, id
• edge case: if 403 returned, cookies are stale. catch and raise error prompting user to refresh cookies via /refresh twitter cookies command
• edge case: if 429 returned, rate limit hit. backoff with exponential delay (start 60s) or abort with message "rate limited, try again in 15 minutes"
• edge case: if empty result set, return empty list without error. user will see "no tweets found"

step 3: filter tweets by quality metrics

• input: raw tweets list, min_likes threshold (default 10), exclude replies (default true)
• filter: keep only tweets where favorite_count >= min_likes AND is_reply == false (unless user specified include replies)
• filter: optionally de-duplicate by tweet id (graphql may return same tweet across pages)
• output: filtered tweets list sorted by favorite_count descending
• edge case: if all tweets filtered out, return empty list

step 4: enrich and format report

• input: filtered tweets list, original query string, date range (if user specified)
• extract: top 5 tweets by engagement, derive key themes (manual categorization or llm-based), identify top 10 authors by follower count
• format output as structured markdown report (see output contract below)
• output: formatted report string ready for display
• edge case: if favorite_count or retweet_count field missing (null), treat as 0

---

phase 2: keyword monitoring (cron-driven)

step 1: load config and state

• input: twitter-monitors.json (list of monitor objects), twitter-monitors-state.json (tracking dict)
• read config file, validate schema (id, query, product, count, min_likes, alert_threshold required)
• read state file or init empty state dict if file doesn't exist
• output: parsed monitors list, parsed state dict
• edge case: if config file malformed json, raise error with line number

step 2: iterate enabled monitors

• input: monitors list from step 1
• filter: keep only monitors where "enabled": true
• for each enabled monitor:
  • extract: id, query, product, count, min_likes, alert_threshold
  • output: monitor object to pass to step 3
• edge case: if no enabled monitors, log "no active monitors" and exit gracefully

step 3: search and diff

• input: monitor object, authenticated client, state dict
• call await client.search_tweets(query, count, product) (same as phase 1 step 2)
• filter by min_likes (same as phase 1 step 3)
• load last_tweet_ids from state[monitor_id] (default empty list if first run)
• diff: identify new tweets not in last_tweet_ids
• output: new tweets list, all tweets (for state update)
• edge case: if search fails (403, 429, timeout), log error, skip this monitor, move to next

step 4: check alert threshold and persist

• input: new tweets list, alert_threshold from monitor, monitor_id
• filter: tweets where favorite_count >= alert_threshold
• if any high-engagement tweets found:
  • immediately send alert to user (format: "new high-engagement tweet on [keyword]")
  • include: tweet text, author, engagement counts, link
• persist all new tweets to daily file: {monitor_id}/YYYY-MM-DD.json (append mode, handle dayroll-over at midnight)
• output: alert message (or empty if no threshold breaches), persisted tweets
• edge case: if write to disk fails, log error but don't crash. attempt to save state anyway

step 5: update state file

• input: monitor_id, all tweets from step 3, current timestamp
• update state[monitor_id]:
  • last_run: current iso 8601 timestamp
  • last_tweet_ids: list of all tweet ids from this run (keep only most recent 500 to avoid unbounded state growth)
  • total_collected: increment by count of new tweets
• write state dict back to twitter-monitors-state.json (atomic write, write to temp file then rename)
• output: updated state file on disk
• edge case: if concurrent cron jobs running, state file may be locked. retry 3 times with 5s backoff, then skip

step 6: send summary notification

• input: all monitors' results from this cron run
• if at least one monitor found new high-engagement tweets:
  • send single summary message: "twitter monitoring summary: [N] new alerts across [M] keywords"
  • include count of new tweets per monitor
• output: notification sent or skipped if no new tweets
• edge case: if notification system unavailable, log and continue

---

phase 3: trend analysis

step 1: load historical data

• input: monitor_id string
• scan directory {monitor_id}/ for all daily files matching YYYY-MM-DD.json
• read and parse all json files into single list of tweets
• output: merged tweets list with all historical data for monitor
• edge case: if directory doesn't exist or is empty, return empty list and inform user "no data yet, check back after monitoring runs"

step 2: group by week

• input: tweets list from step 1
• for each tweet, extract created_at timestamp, derive iso week number (monday start)
• group tweets by (year, week_number)
• output: dict mapping week_key -> tweets list
• edge case: if tweet missing created_at field, skip it with warning log

step 3: compute weekly metrics

• input: grouped tweets dict from step 2
• for each week:
  • count: total tweets, total favorites, total retweets, total views
  • top 5: tweets sorted by favorite_count descending
  • authors: list of unique authors in this week, sorted by follower_count descending (take top 10)
  • themes: manually label or use llm to categorize top tweets into 3-5 themes
  • sentiment: rough heuristic (ratio of emoji/positive words vs negative words) or skip if unreliable
• output: dict mapping week_key -> {tweet_count, total_engagement, top_tweets, top_authors, themes, sentiment}
• edge case: if follower_count missing on author object, use 0

step 4: generate narrative

• input: weekly metrics dict from step 3, monitor_id (keyword)
• produce markdown report with:
  • header: "Trend Report: [keyword]"
  • intro: date range covered, total tweets analyzed
  • week-by-week section: for each week in chronological order, state metrics + top themes + new authors + sentiment shift
  • summary: highest engagement week, most common themes across all weeks, emerging vs declining topics
• output: markdown string ready for display or export
• edge case: if only 1 week of data, omit "trend" and just show summary snapshot

---

decision points

if cookies not found or path undefined:

• raise error instructing user to set TWITTER_COOKIES_PATH env var and extract fresh cookies from x.com

if search returns 403 (forbidden):

• cookies are expired