TwitterApi Research

General-purpose X/Twitter research agent. Searches X for real-time perspectives, dev discussions, product feedback, cultural takes, breaking news, and expert...

Security Scan

The skill is broadly what it claims (a Twitter/X research CLI using twitterapi.io) but the bundle metadata omits that it requires a twitterapi.io API key and the runtime instructions ask you to source a global env file (which can expose unrelated secrets), so the package and its manifest are inconsistent and deserve caution before installing.

Purpose & Capability

The code and SKILL.md clearly require a TWITTERAPI_IO_KEY and Bun to run, which is coherent with a twitterapi.io-based research tool — but the registry metadata lists no required environment variables or primary credential. That mismatch (manifest says 'none' while runtime code insists on an API key) is a material inconsistency.

Instruction Scope

SKILL.md and README instruct the user/agent to 'source ~/.config/env/global.env' and the code will read that file to extract TWITTERAPI_IO_KEY. Sourcing a global env file can expose many unrelated environment variables to the shell/agent session and agent logs. Apart from that, the instructions stick to search/profile/thread workflows and fetching linked web resources (web_fetch) which is expected for research, but the explicit guidance to source a global env file expands the skill's read scope beyond only the Twitter key.

Install Mechanism

No remote install/downloads or obscure URLs are used; this skill is provided as source files and is run with Bun per the README. There is no install spec that would fetch arbitrary code at runtime. The only external dependency is the third-party API (twitterapi.io) which is expected for this purpose.

Credentials

The runtime requires TWITTERAPI_IO_KEY (read from env or ~/.config/env/global.env) but the registry metadata does not declare this or any primary credential. The skill also accesses HOME paths (writes drafts to ~/clawd/drafts and a watchlist under the skill data directory). Requesting a single API key is proportionate to the stated purpose, but the manifest omission and instruction to source a global env file (potentially exposing other secrets) are disproportionate and risky.

Persistence & Privilege

The skill does local, expected file writes (cache, data/watchlist.json, and optional saved drafts) within its own skill directory and a drafts directory under the user's home. It does not request always:true, nor does it appear to modify other skills or system-wide configs. No elevated persistence is requested.

What to consider before installing

Do not install blindly. The code requires a twitterapi.io API key (TWITTERAPI_IO_KEY) even though the registry metadata doesn't declare it—that mismatch is a red flag. Before installing: (1) verify the skill source (review the GitHub repo or author) and confirm you trust twitterapi.io; (2) avoid 'sourcing' a global env file that may contain many other secrets—prefer storing the TWITTERAPI_IO_KEY in a dedicated secret store or an agent-specific environment variable; (3) be aware agent session logs or tooling may record HTTP headers/commands (the README warns your API key could appear in logs), and rotate the key if you suspect exposure; (4) note this tool writes caches, a watchlist and saved drafts to your home directory—review those paths if privacy matters; (5) ensure Bun is acceptable in your environment. If the author can update the registry metadata to declare TWITTERAPI_IO_KEY (and any other required vars) and remove guidance to source a global env containing unrelated secrets, the inconsistency would be resolved and this would look far more benign.

X Research

General-purpose agentic research over X/Twitter. Decompose any research question into targeted searches, iteratively refine, follow threads, deep-dive linked content, and synthesize into a sourced briefing.

For twitterapi.io API details (endpoints, operators, response format): read references/x-api.md.

CLI Tool

All commands run from this skill directory:

cd ~/clawd/skills/x-research
source ~/.config/env/global.env  # needs TWITTERAPI_IO_KEY

Search

bun run x-search.ts search "<query>" [options]

Options:

• --sort likes|impressions|retweets|recent — sort order (default: likes)
• --since 1h|3h|12h|1d|7d — time filter (default: last 7 days). Also accepts minutes (30m) or ISO timestamps.
• --min-likes N — filter by minimum likes
• --min-impressions N — filter by minimum impressions
• --pages N — pages to fetch, 1-25 (default: 5, ~20 tweets/page)
• --limit N — max results to display (default: 15)
• --quick — quick mode: 1 page, max 10 results, auto noise filter (-is:retweet -is:reply), 1hr cache, cost summary
• --from <username> — shorthand for from:username in query
• --quality — filter low-engagement tweets (≥10 likes, post-hoc)
• --no-replies — exclude replies
• --save — save results to ~/clawd/drafts/x-research-{slug}-{date}.md
• --json — raw JSON output
• --markdown — markdown output for research docs

Auto-adds -is:retweet unless query already includes it. All searches display estimated API cost.

Note: twitterapi.io search covers full archive (not limited to 7 days). Time filtering uses since: operator in the query.

Examples:

bun run x-search.ts search "BNKR" --sort likes --limit 10
bun run x-search.ts search "from:frankdegods" --sort recent
bun run x-search.ts search "(opus 4.6 OR claude) trading" --pages 2 --save
bun run x-search.ts search "$BNKR (revenue OR fees)" --min-likes 5
bun run x-search.ts search "BNKR" --quick
bun run x-search.ts search "BNKR" --from voidcider --quick
bun run x-search.ts search "AI agents" --quality --quick

Profile

bun run x-search.ts profile <username> [--count N] [--replies] [--json]

Fetches recent tweets from a specific user (excludes replies by default).

Thread

bun run x-search.ts thread <tweet_id> [--pages N]

Fetches full conversation thread by root tweet ID.

Single Tweet

bun run x-search.ts tweet <tweet_id> [--json]

Watchlist

bun run x-search.ts watchlist                       # Show all
bun run x-search.ts watchlist add <user> [note]     # Add account
bun run x-search.ts watchlist remove <user>          # Remove account
bun run x-search.ts watchlist check                  # Check recent from all

Watchlist stored in data/watchlist.json. Use for heartbeat integration — check if key accounts posted anything important.

Cache

bun run x-search.ts cache clear    # Clear all cached results

15-minute TTL. Avoids re-fetching identical queries.

Research Loop (Agentic)

When doing deep research (not just a quick search), follow this loop:

1. Decompose the Question into Queries

Turn the research question into 3-5 keyword queries using X search operators:

• Core query: Direct keywords for the topic
• Expert voices: from: specific known experts
• Pain points: Keywords like (broken OR bug OR issue OR migration)
• Positive signal: Keywords like (shipped OR love OR fast OR benchmark)
• Links: url:github.com or url: specific domains
• Noise reduction: -is:retweet (auto-added), add -is:reply if needed
• Crypto spam: Add -airdrop -giveaway -whitelist if crypto topics flooding

2. Search and Extract

Run each query via CLI. After each, assess:

• Signal or noise? Adjust operators.
• Key voices worth searching from: specifically?
• Threads worth following via thread command?
• Linked resources worth deep-diving with web_fetch?

3. Follow Threads

When a tweet has high engagement or is a thread starter:

bun run x-search.ts thread <tweet_id>

4. Deep-Dive Linked Content

When tweets link to GitHub repos, blog posts, or docs, fetch with web_fetch. Prioritize links that:

• Multiple tweets reference
• Come from high-engagement tweets
• Point to technical resources directly relevant to the question

5. Synthesize

Group findings by theme, not by query:

### [Theme/Finding Title]

[1-2 sentence summary]

- @username: "[key quote]" (NL, NI) [Tweet](url)
- @username2: "[another perspective]" (NL, NI) [Tweet](url)

Resources shared:
- [Resource title](url) — [what it is]

6. Save

Use --save flag or save manually to ~/clawd/drafts/x-research-{topic-slug}-{YYYY-MM-DD}.md.

Refinement Heuristics

• Too much noise? Add -is:reply, use --sort likes, narrow keywords
• Too few results? Broaden with OR, remove restrictive operators
• Crypto spam? Add -$ -airdrop -giveaway -whitelist
• Expert takes only? Use from: or --min-likes 50
• Substance over hot takes? Search with has:links

Heartbeat Integration

On heartbeat, can run watchlist check to see if key accounts posted anything notable. Flag to Frank only if genuinely interesting/actionable — don't report routine tweets.

File Structure

skills/x-research/
├── SKILL.md           (this file)
├── x-search.ts        (CLI entry point)
├── lib/
│   ├── api.ts         (twitterapi.io wrapper: search, thread, profile, tweet)
│   ├── cache.ts       (file-based cache, 15min TTL)
│   └── format.ts      (Telegram + markdown formatters)
├── data/
│   ├── watchlist.json  (accounts to monitor)
│   └── cache/          (auto-managed)
└── references/
    └── x-api.md        (twitterapi.io endpoint reference)