mention-radar

${var} — Comma-separated project names to track (e.g. "MyApp, my-lib"). If empty, derives targets from MEMORY.md and memory/topics/projects.md.

Read memory/MEMORY.md for current project status. Read the last 3 days of memory/logs/ to avoid re-surfacing already-noted mentions.

Steps

1. Define the targets.

   • If ${var} is set: parse it as a comma-separated list of project names.
   • Otherwise: scan memory/MEMORY.md (goals, active topics) and memory/topics/projects.md (if it exists) for the operator's active projects. A target needs at least a name; collect a site/domain and a GitHub owner/repo too when known.
   • Cap at 6 targets — prefer the most active ones.
   • If zero targets can be derived: log MENTION_RADAR_SKIP: no projects configured — set var or add projects to memory/topics/projects.md and stop. No notification.

   For each target, build search terms:

   • The exact project name in quotes (e.g. "MyApp" site:x.com OR site:reddit.com OR site:news.ycombinator.com)
   • The domain if known (e.g. "myapp.xyz")
   • The repo if known (e.g. site:github.com owner/myapp)

2. Search for external mentions. X/Twitter is fetched via twitterapi.io (primary); xAI Grok x_search is the fallback; the rest of the public web (Reddit, Farcaster, blogs, newsletters, GitHub Discussions, HN, Product Hunt) goes through WebSearch, which is also the last-resort fallback for X itself. Derive the operator's handle from soul/SOUL.md if present (call it $OPERATOR) so you can exclude their own posts.

   Shell shape. Each Bash call is one allowed command (pipes are fine). The run refuses a call that sets a variable (FROM_DATE=$(date ...), Q="...", HTTP=$(./secretcurl ...)), uses if / for / while or [ -n ... ] && tests, or joins commands with ;, && or ||, and each refusal costs a model turn. So get a date with a bare date call and write the printed value into later commands; write each target's name, domain, repo, the operator handle and the dates into each command literally (the <NAME>, <FROM_DATE> style placeholders in the snippets), jq filters included (a jq $name variable from --arg is refused, and so is a > redirect into a file, so the xAI body is piped straight into ./secretcurl ... --data-binary @-); loop over targets by making one call per target; run one jq per call.

   Get the window dates first, each date as its own Bash call:

   date -u -d '7 days ago' +%Y-%m-%d
   

   date -u +%Y-%m-%d
   

   The first prints FROM_DATE, the second TO_DATE.

   Path A - twitterapi.io (primary, X/Twitter mentions). For each target, structured search for other people mentioning the project. See the Fetching contract below. Use a unique tmp filename per target if you loop (e.g. /tmp/tw-mr-<SLUG>.json). <NAME>/<DOMAIN>/<REPO> come from the target built in step 1, written in literally. Put the date window inside the query with since:/until:; exclude the operator with -from:. <QUERY> is "<NAME>" -from:<OPERATOR> since:<FROM_DATE> until:<TO_DATE>, then OR "<DOMAIN>" added when the target has a domain and OR "<REPO>" added when it has a repo (leave each out when empty), all written in literally. One call per target:

   ./secretcurl -s -o /tmp/tw-mr.json -w 'twitterapi http=%{http_code} bytes=%{size_download}\n' --max-time 60 -G "https://api.twitterapi.io/twitter/tweet/advanced_search" \
     --data-urlencode 'query=<QUERY>' --data-urlencode "queryType=Latest" \
     -H "X-API-Key: {TWITTER_API_KEY}"
   

   On HTTP=200 with a non-empty .tweets[], parse and mark X_SOURCE=twitterapi. Drop posts by $OPERATOR and the project's own accounts if any slipped through:

   jq -r '.tweets[] | [.id, .author.userName, .text, .url, .createdAt, .likeCount, .retweetCount, .replyCount] | @tsv' /tmp/tw-mr.json
   

   Engagement counts are exact; permalinks are .url. createdAt is Twitter-native (Wed Sep 09 20:21:43 +0000 2026); normalize with strptime("%a %b %d %H:%M:%S %z %Y") before any date compare. advanced_search does not return author.followers - omit follower counts on this path (Path B can supply them).

   Path B - xAI Grok x_search (fallback). Only if Path A returned non-2xx / empty / timeout, or TWITTER_API_KEY is unset. See the Fetching contract - set the Bash tool timeout to ≥180000, and capture the HTTP status. Use a unique tmp filename per target if you loop (e.g. /tmp/xai-mr-<SLUG>.json). Build the body with the prompt inline and every value written into the jq filter literally (a " inside a value becomes \", and reword any '), and pipe it straight into the send:

   jq -n '{model:"grok-4.7", input:[{role:"user",content:"Search X for posts by OTHER people mentioning the project \"<NAME>\" (also its site <DOMAIN> and repo <REPO> when given), posted between <FROM_DATE> and <TO_DATE>. Exclude posts by the operator @<OPERATOR> and by the accounts of the project itself. For each mention return: @handle, the full post text, date, exact engagement counts (likes, retweets, replies; 0 if unknown), the approximate follower count of the poster if visible, and the direct link https://x.com/handle/status/ID. Prioritize people discovering it for the first time, asking confused questions, hitting friction (setup/docs/missing feature), comparing it to a competitor, or requesting a feature. Return a numbered list; if nobody is talking about it, say so explicitly."}], tools:[{type:"x_search",from_date:"<FROM_DATE>",to_date:"<TO_DATE>"}]}' \
     | ./secretcurl -s -o /tmp/xai-mr.json -w '%{http_code}' --max-time 150 -X POST "https://api.x.ai/v1/responses" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer {XAI_API_KEY}" \
     --data-binary @-
   

   On HTTP=200 with a non-empty body, parse /tmp/xai-mr.json with jq -r '.output[] | select(.type == "message") | .content[] | select(.type == "output_text") | .text' and feed the X mentions into categorization (step 4). Record X_SOURCE=api.

   Path C - WebSearch (broader web + X last resort). Always use WebSearch for the non-X surfaces - Reddit, Farcaster, personal blogs, newsletters, GitHub Discussions, HN, Product Hunt:

   • Try both brand name and URL variants
   • Time-box to last 7 days where the search engine supports it
   • Skip results from the operator's own accounts and the project's own repos

   WebSearch is also the last-resort fallback for X/Twitter, but only when Paths A and B both truly failed (key-unset, http-<code>, empty, or timeout - record the real reason per the Fetching contract, never "XAI_API_KEY unavailable" / "TWITTER_API_KEY unavailable" when a key was set). On the X fallback query site:x.com "<project name>" after:${FROM_DATE}; note in the log that X results came from WebSearch (lower quality) and set X_SOURCE=websearch.

3. Also check GitHub network signals for each target with a known repo:

   gh api repos/OWNER/REPO --jq '{stars: .stargazers_count, forks: .forks_count, watchers: .watchers_count}'
   

   Skip any repo that 404s (private or not yet public). Compare to the last log entry to compute deltas. If no prior data, record as baseline.

4. Categorize each mention found:

   • Discovery — person found the project for the first time, sharing it, impressed ("this is cool", star notification, share)
   • Confusion — person unclear on what it does, asking questions, mischaracterizing it
   • Friction — person ran into a problem (setup, docs, missing feature)
   • Competitor comparison — mentioned alongside or against a competing project
   • Feature request / wish — explicit ask for something missing
   • Press / newsletter — cited in a publication or digest

5. Identify engagement opportunities. Flag any mention where:

   • The person is confused and a 1-tweet clarification would help
   • A feature request aligns with what's being built
   • A competitor comparison is wrong or incomplete
   • A high-follower account discovered the project (high-leverage reply opportunity)

6. Format the output (under 4000 chars):

   *Mention Radar - ${today}*
   
   {PROJECT NAME, uppercased}
   - [source] - [what they said] - [category]
   ...
   (one section per target)
   
   ENGAGEMENT OPPORTUNITIES
   - [handle/source]: [why worth replying]
   
   QUIET: [project] - no external mentions found
   

   Use QUIET: [project] for any project with zero external mentions this cycle. Skip GitHub-only star delta if it's less than 5 — only mention notable jumps.

7. Only notify if there's signal. Skip notification if ALL projects are quiet and no GitHub deltas > 5 stars. Log MENTION_RADAR_QUIET instead.

8. Send via ./notify if there's anything worth surfacing.

9. Log to memory/logs/${today}.md:

   ### mention-radar
   - **{project}:** [N mentions / QUIET]
   (one line per target)
   - **Top find:** [best mention in one line, or "none"]
   - **Engagement opps:** [N flagged, or 0]
   - **Notification sent:** yes/no
   

Guidelines

• This is signal filtering, not a metrics report. One real conversation > ten impressions.
• Prioritize quality of mention over quantity. A thoughtful Reddit post or HN comment matters more than a retweet.
• Don't manufacture urgency. If there's nothing worth acting on, say so.
• Be specific — link the source, quote the key line, name the person if identifiable.
• The point is engagement opportunity and awareness, not vanity numbers.

Fetching

TWITTER_API_KEY is injected into your environment for this skill (declared in requires:). The primary fetch path for X/Twitter mentions is a direct curl to https://api.twitterapi.io/twitter/tweet/advanced_search with header X-API-Key: {TWITTER_API_KEY} (step 2, Path A). Grok x_search (XAI_API_KEY) is the fallback. There is no network sandbox blocking this. Just make the call.

You MUST attempt twitterapi.io before any X fallback. The rules:

1. Check, don't assume. Read the "Keys set for this run" line in your run notes, never a shell test (those are refused and cost a turn): TWITTER_API_KEY on that line = KEY_PRESENT, not on it = KEY_UNSET. If KEY_PRESENT, you are required to try Path A.
2. Capture the HTTP status so the fallback decision is based on fact. Print http=<code> before parsing. HTTP=200 with a non-empty .tweets[] → use it (X_SOURCE=twitterapi). Put date windows inside the query with since:YYYY-MM-DD until:YYYY-MM-DD. createdAt is Twitter-native (Wed Sep 09 20:21:43 +0000 2026), not ISO - normalize with strptime("%a %b %d %H:%M:%S %z %Y") before any date compare.
3. Path B - xAI Grok x_search (fallback). Only when Path A fails (non-2xx / empty / timeout) or TWITTER_API_KEY is unset. Direct curl to https://api.x.ai/v1/responses with Authorization: Bearer {XAI_API_KEY}. The x_search call typically takes 30-120s - set the Bash tool timeout to at least 180000 (180s) and keep --max-time 150 on the curl. A slow curl is not a missing key. Build the payload with the jq -n filter shown in step 2 Path B (values written in literally) and pipe it straight into the send - a > redirect into a file is refused, and the ./secretcurl command must stay 100% literal (no $VAR):

   jq -n '{...}' | ./secretcurl -s -o /tmp/xai-mr.json -w '%{http_code}' --max-time 150 -X POST "https://api.x.ai/v1/responses" \
     -H "Content-Type: application/json" -H "Authorization: Bearer {XAI_API_KEY}" --data-binary @-
   

   It prints the status code (HTTP); ./secretcurl also prints an http=... bytes=... line on stderr. Then parse /tmp/xai-mr.json with the standard jq extractor. HTTP=200 with a non-empty body → use it (X_SOURCE=api).
4. Fall back only on a real failure, and record the true reason - never write "XAI_API_KEY unavailable" / "TWITTER_API_KEY unavailable" when a key was set. Use one of: key-unset (only if step 1 said KEY_UNSET), http-<code> (non-2xx), empty (200 but no mentions parsed), timeout (curl exceeded --max-time).

WebSearch / WebFetch are last-resort fallbacks only for X - lower quality (WebSearch favours old high-engagement tweets). They remain the primary tool for the non-X web surfaces (Reddit, HN, blogs, etc.). Never reach for the X WebSearch fallback while a key works.

Environment Variables

• TWITTER_API_KEY - twitterapi.io API key (sent as the X-API-Key header). Declared in requires:, so it is injected into this skill's environment and is the primary path for X/Twitter mentions.
• XAI_API_KEY - X.AI API key for Grok's x_search tool. Declared in requires: (optional ?). The fallback path when TWITTER_API_KEY is unset or twitterapi returns non-2xx / empty / timeout. If both keys are unset, X mentions degrade to the WebSearch fallback at lower quality; the broader-web search is unaffected.
• gh CLI — pre-authenticated in GitHub Actions; used for the GitHub network-signal check (step 3). Not an env var you set here.