X 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 mostly does what it says (search X/Twitter), but it fails to declare its required credentials and instructs/implements reading a user-wide env file (~/.config/env/global.env), which is disproportionate and potentially exposes unrelated secrets.

Purpose & Capability

The code and SKILL.md implement a Twitter/X research CLI (search, thread, profile, watchlist, caching) which matches the skill description. However the registry metadata declares no required env vars or binaries, while the README/SKILL.md and code clearly require a X_BEARER_TOKEN and Bun to run. That's an inconsistency: the requested runtime capabilities are missing from the declared metadata.

Instruction Scope

Runtime instructions and the code instruct the agent/user to source ~/.config/env/global.env and the API wrapper will read that file if X_BEARER_TOKEN isn't in env. Reading a global.env file (or asking users to source it) is broader than necessary for a single-service token because it may expose other unrelated secrets. The SKILL.md also tells the agent to use web_fetch for linked content (expected for research) but gives the agent discretion to 'deep-dive' links — reasonable for purpose but expands network surface.

Install Mechanism

There is no formal install spec in the registry (instruction-only), but the README and SKILL.md expect the repo to be cloned and Bun to be installed. No arbitrary remote downloads or extract operations are present in the package files. The lack of declared required binaries (bun) in the registry is an oversight but not an active install risk.

Credentials

The code requires an X_BEARER_TOKEN (documented in README and used in lib/api.ts) yet the skill metadata lists no required environment variables or primary credential. Additionally, the code will attempt to read ~/.config/env/global.env if the env var is absent — this can expose other environment values in that file. The skill also writes to user paths (~/clawd/drafts) and a local cache; those writes are proportionate to the tool but the undeclared credential requirement and reading of a general-purpose env file are disproportionate.

Persistence & Privilege

The skill does not request always:true, does not modify other skills, and has normal file persistence (cache, watchlist, drafts) within its directory and the user's ~/clawd/drafts. Writing/reading these files is expected for the feature set and within the skill's scope.

What to consider before installing

This skill implements an X/Twitter research CLI and will need your X API bearer token to work — but the registry metadata fails to declare that. Before installing: (1) confirm you are comfortable providing an X_BEARER_TOKEN to this skill; prefer exporting the token specifically for this skill rather than storing many secrets in a shared file. (2) Note the code will try to read ~/.config/env/global.env if the env var isn't set — review that file contents to ensure it doesn't contain unrelated secrets. (3) The skill writes cache and drafts to your filesystem (data/cache and ~/clawd/drafts); run it in an isolated workspace if you want to limit impacts. (4) The code talks only to api.x.com (the X API) — review the files yourself if you need extra assurance. (5) If you plan to let agents invoke this skill autonomously, be extra cautious: undeclared credential access plus autonomous invocation increases blast radius. If the author can update the registry metadata to declare X_BEARER_TOKEN and required bun binary, and modify the code to avoid reading a general-purpose env file (or at least make that behavior opt-in and documented), the remaining concerns would be reduced.

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 X 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

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-5 (default: 1, 100 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.

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         (X API 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        (X API endpoint reference)