dvcrn xint — X Intelligence CLI
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.
Security Considerations
This skill requires sensitive credentials. Follow these guidelines:
Credentials
- X_BEARER_TOKEN: Required for X API. Treat as a secret - prefer exported environment variables (optional project-local
.env) - XAI_API_KEY: Optional, needed for AI analysis. Also a secret
- X_CLIENT_ID: Optional, needed for OAuth. Less sensitive but don't expose publicly
- XAI_MANAGEMENT_API_KEY: Optional, for collections management
File Writes
- This skill writes to its own
data/directory: cache, exports, snapshots, OAuth tokens - OAuth tokens stored with restrictive permissions (chmod 600)
- Review exported data before sharing - may contain sensitive search queries
Webhooks
watchandstreamcan send data to webhook endpoints- Remote endpoints must use
https://(http://is accepted only for localhost/loopback) - Optional host allowlist:
XINT_WEBHOOK_ALLOWED_HOSTS=hooks.example.com,*.internal.example - Avoid sending sensitive search queries or token-bearing URLs to third-party destinations
Runtime Notes
- This file documents usage and safety controls for the CLI only.
- Network listeners are opt-in (
mcp --sse) and disabled by default - Webhook delivery is opt-in (
--webhook) and disabled by default
Installation
- For Bun: prefer OS package managers over
curl | bashwhen possible - Verify any installer scripts before running
MCP Server (Optional)
bun run xint.ts mcpstarts a local MCP server exposing xint commands as tools- Default mode is stdio/local integration; no inbound web server unless
--sseis explicitly enabled - Respect
--policy read_only|engagement|moderationand budget guardrails
CLI Tool
All commands run from the project directory:
# Set your environment variables
export X_BEARER_TOKEN="your-token"
Search
bun run xint.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, 1hr cache, cost summary--from <username>— shorthand forfrom:usernamein query--quality— filter low-engagement tweets (>=10 likes, post-hoc)--no-replies— exclude replies--sentiment— AI-powered per-tweet sentiment analysis (via Grok). Shows positive/negative/neutral/mixed with scores.--save— save results todata/exports/--json— raw JSON output--jsonl— one JSON object per line (optimized for Unix pipes:| jq,| tee)--csv— CSV output for spreadsheet analysis--markdown— markdown output for research docs
Auto-adds -is:retweet unless query already includes it. All searches display estimated API cost.
Examples:
bun run xint.ts search "AI agents" --sort likes --limit 10
bun run xint.ts search "from:elonmusk" --sort recent
bun run xint.ts search "(opus 4.6 OR claude) trading" --pages 2 --save
bun run xint.ts search "$BTC (revenue OR fees)" --min-likes 5
bun run xint.ts search "AI agents" --quick
bun run xint.ts search "AI agents" --quality --quick
bun run xint.ts search "solana memecoins" --sentiment --limit 20
bun run xint.ts search "startup funding" --csv > funding.csv
bun run xint.ts search "AI" --jsonl | jq 'select(.metrics.likes > 100)'
Profile
bun run xint.ts profile <username> [--count N] [--replies] [--json]
Fetches recent tweets from a specific user (excludes replies by default).
Thread
bun run xint.ts thread <tweet_id> [--pages N]
Fetches full conversation thread by root tweet ID.
Single Tweet
bun run xint.ts tweet <tweet_id> [--json]
Article (Full Content Fetcher)
bun run xint.ts article <url> [--json] [--full] [--ai <text>]
Fetches and extracts full article content from any URL using xAI's web_search tool (Grok reads the page). Returns clean text with title, author, date, and word count. Requires XAI_API_KEY.
Also supports X tweet URLs — automatically extracts the linked article from the tweet and fetches it.
Options:
--json— structured JSON output (title, content, author, published, wordCount, ttr)--full— return full article text without truncation (default truncates to ~5000 chars)--model <name>— Grok model (default: grok-4)--ai <text>— analyze article with Grok AI (passes content to analyze command)
Examples:
# Fetch article from URL
bun run xint.ts article https://example.com/blog/post
# Auto-extract article from X tweet URL and analyze
bun run xint.ts article "https://x.com/user/status/123456789" --ai "Summarize key takeaways"
# Fetch + analyze with AI
bun run xint.ts article https://techcrunch.com/article --ai "What are the main points?"
# Full content without truncation
bun run xint.ts article https://blog.example.com/deep-dive --full
Agent usage: When search results include tweets with article links, use article to read the full content. Search results now include article titles and descriptions from the X API (shown as 📰 lines), so you can decide which articles are worth a full read. Prioritize articles that:
- Multiple tweets reference
- Come from high-engagement tweets
- Have relevant titles/descriptions from the API metadata
Bookmarks
bun run xint.ts bookmarks [options] # List bookmarked tweets
bun run xint.ts bookmark <tweet_id> # Bookmark a tweet
bun run xint.ts unbookmark <tweet_id> # Remove a bookmark
Bookmark list options:
--limit N— max bookmarks to display (default: 20)--since <dur>— filter by recency (1h, 1d, 7d, etc.)--query <text>— client-side text filter--json— raw JSON output--markdown— markdown output--save— save to data/exports/--no-cache— skip cache
Requires OAuth. Run auth setup first.
Likes
bun run xint.ts likes [options] # List your liked tweets
bun run xint.ts like <tweet_id> # Like a tweet
bun run xint.ts unlike <tweet_id> # Unlike a tweet
Likes list options: Same as bookmarks (--limit, --since, --query, --json, --no-cache).
Requires OAuth with like.read and like.write scopes.
Following
bun run xint.ts following [username] [--limit N] [--json]
Lists accounts you (or another user) follow. Defaults to the authenticated user.
Requires OAuth with follows.read scope.
Trends
bun run xint.ts trends [location] [options]
Fetches trending topics. Tries the official X API trends endpoint first; falls back to search-based hashtag frequency estimation if unavailable.
Options:
[location]— location name or WOEID number (default: worldwide)--limit N— number of trends to display (default: 20)--json— raw JSON output--no-cache— bypass the 15-minute cache--locations— list all known location names
Examples:
bun run xint.ts trends # Worldwide
bun run xint.ts trends us --limit 10 # US top 10
bun run xint.ts trends japan --json # Japan, JSON output
bun run xint.ts trends --locations # List all locations
Analyze (Grok AI)
bun run xint.ts analyze "<query>" # Ask Grok a question
bun run xint.ts analyze --tweets <file> # Analyze tweets from JSON file
bun run xint.ts search "topic" --json | bun run xint.ts analyze --pipe # Pipe search results
Uses xAI's Grok API (OpenAI-compatible). Requires XAI_API_KEY in env or .env.
Options:
--model <name>— grok-3, grok-3-mini (default), grok-2--tweets <file>— path to JSON file containing tweets--pipe— read tweet JSON from stdin
Examples:
bun run xint.ts analyze "What are the top AI agent frameworks right now?"
bun run xint.ts search "AI agents" --json | bun run xint.ts analyze --pipe "Which show product launches?"
bun run xint.ts analyze --model grok-3 "Deep analysis of crypto market sentiment"
xAI X Search (No Cookies/GraphQL)
For “recent sentiment / what X is saying” without using cookies/GraphQL, use xAI’s hosted x_search tool.
Script:
python3 scripts/xai_x_search_scan.py --help
xAI Collections Knowledge Base (Files + Collections)
Store first-party artifacts (reports, logs) in xAI Collections and semantic-search them later.
Script:
python3 scripts/xai_collections.py --help
Env:
XAI_API_KEY(api.x.ai): file upload + searchXAI_MANAGEMENT_API_KEY(management-api.x.ai): collections management + attaching documents
Notes:
- Never print keys.
- Prefer
--dry-runwhen wiring new cron jobs.
Watch (Real-Time Monitoring)
bun run xint.ts watch "<query>" [options]
Polls a search query on an interval, shows only new tweets. Great for monitoring topics during catalysts, tracking mentions, or feeding live data into downstream tools.
Options:
--interval <dur>/-i— poll interval:30s,1m,5m,15m(default: 5m)--webhook <url>— POST new tweets as JSON to this URL (https://required for remote hosts)--jsonl— output as JSONL instead of formatted text (for piping totee,jq, etc.)--quiet— suppress per-poll headers (just show tweets)--limit N— max tweets to show per poll--sort likes|impressions|retweets|recent— sort order
Press Ctrl+C to stop — prints session stats (duration, total polls, new tweets found, total cost).
Examples:
bun run xint.ts watch "solana memecoins" --interval 5m
bun run xint.ts watch "@vitalikbuterin" --interval 1m
bun run xint.ts watch "AI agents" -i 30s --webhook https://hooks.example.com/ingest
bun run xint.ts watch "breaking news" --jsonl | tee -a feed.jsonl
Agent usage: Use watch when you need continuous monitoring of a topic. For one-off checks, use search instead. The watch command auto-stops if the daily budget is exceeded.
Diff (Follower Tracking)
bun run xint.ts diff <@username> [options]
Tracks follower/following changes over time using local snapshots. First run creates a baseline; subsequent runs show who followed/unfollowed since last check.
Options:
--following— track who the user follows (instead of their followers)--history— view all saved snapshots for this user--json— structured JSON output--pages N— pages of followers to fetch (default: 5, 1000 per page)
Requires OAuth (auth setup first). Snapshots stored in data/snapshots/.
Examples:
bun run xint.ts diff @vitalikbuterin # First run: create snapshot
bun run xint.ts diff @vitalikbuterin # Later: show changes
bun run xint.ts diff @0xNyk --following # Track who you follow
bun run xint.ts diff @solana --history # View snapshot history
Agent usage: Use diff to detect notable follower changes for monitored accounts. Combine with watch for comprehensive account monitoring. Run periodically (e.g., daily) to build a history of follower changes.
Report (Intelligence Reports)
bun run xint.ts report "<topic>" [options]
Generates comprehensive markdown intelligence reports combining search results, optional sentiment analysis, and AI-powered summary via Grok.
Options:
--sentiment— include per-tweet sentiment analysis--accounts @user1,@user2— include per-account activity sections--model <name>— Grok model for AI summary (default: grok-3-mini)--pages N— search pages to fetch (default: 2)--save— save report todata/exports/
Examples:
bun run xint.ts report "AI agents"
bun run xint.ts report "solana" --sentiment --accounts @aaboronkov,@rajgokal --save
bun run xint.ts report "crypto market" --model grok-3 --sentiment --save
Agent usage: Use report when the user wants a comprehensive briefing on a topic. This is the highest-level command — it runs search, sentiment, and analysis in one pass and produces a structured markdown report. For quick pulse checks, use search --quick instead.
Costs
bun run xint.ts costs # Today's costs
bun run xint.ts costs week # Last 7 days
bun run xint.ts costs month # Last 30 days
bun run xint.ts costs all # All time
bun run xint.ts costs budget # Show budget info
bun run xint.ts costs budget set 2.00 # Set daily limit to $2
bun run xint.ts costs reset # Reset today's data
Tracks per-call API costs with daily aggregates and configurable budget limits.
Watchlist
bun run xint.ts watchlist # Show all
bun run xint.ts watchlist add <user> [note] # Add account
bun run xint.ts watchlist remove <user> # Remove account
bun run xint.ts watchlist check # Check recent from all
Auth
bun run xint.ts auth setup [--manual] # Set up OAuth 2.0 (PKCE)
bun run xint.ts auth status # Check token status
bun run xint.ts auth refresh # Manually refresh tokens
Required scopes: bookmark.read bookmark.write tweet.read users.read like.read like.write follows.read offline.access
Cache
bun run xint.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.comorurl:specific domains - Noise reduction:
-is:retweet(auto-added), add-is:replyif needed
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
threadcommand? - Linked resources worth deep-diving?
3. Follow Threads
When a tweet has high engagement or is a thread starter:
bun run xint.ts thread <tweet_id>
4. Deep-Dive Linked Content
Search results now include article titles and descriptions from the X API (shown as 📰 in output). Use these to decide which links are worth a full read, then fetch with xint article:
bun run xint.ts article <url> # terminal display
bun run xint.ts article <url> --json # structured output
bun run xint.ts article <url> --full # no truncation
Prioritize links that:
- Multiple tweets reference
- Come from high-engagement tweets
- Have titles/descriptions suggesting depth (not just link aggregators)
- Point to technical resources directly relevant to the question
5. Analyze with Grok
For complex research, pipe search results into Grok for synthesis:
bun run xint.ts search "topic" --json | bun run xint.ts analyze --pipe "Summarize themes and sentiment"
6. 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]
7. Save
Use --save flag to save to data/exports/.
Cost Management
All API calls are tracked in data/api-costs.json. The budget system warns when approaching limits but does not block calls (passive).
X API v2 pay-per-use rates:
- Tweet reads (search, bookmarks, likes, profile): ~$0.005/tweet
- Full-archive search: ~$0.01/tweet
- Write operations (like, unlike, bookmark, unbookmark): ~$0.01/action
- Profile lookups: ~$0.005/lookup
- Follower/following lookups: ~$0.01/page
- Trends: ~$0.10/request
- Grok AI (sentiment/analyze/report): billed by xAI separately (not X API)
Default daily budget: $1.00 (adjustable via costs budget set <N>).
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
File Structure
xint/
├── SKILL.md (this file — agent instructions)
├── xint.ts (CLI entry point)
├── lib/
│ ├── api.ts (X API wrapper: search, thread, profile, tweet)
│ ├── article.ts (full article content fetcher via xAI web_search)
│ ├── bookmarks.ts (bookmark read — OAuth)
│ ├── cache.ts (file-based cache, 15min TTL)
│ ├── costs.ts (API cost tracking & budget)
│ ├── engagement.ts (likes, like/unlike, following, bookmark write — OAuth)
│ ├── followers.ts (follower/following tracking + snapshot diffs)
│ ├── format.ts (terminal, markdown, CSV, JSONL formatters)
│ ├── grok.ts (xAI Grok analysis integration)
│ ├── oauth.ts (OAuth 2.0 PKCE auth + token refresh)
│ ├── report.ts (intelligence report generation)
│ ├── sentiment.ts (AI-powered sentiment analysis via Grok)
│ ├── trends.ts (trending topics — API + search fallback)
│ └── watch.ts (real-time monitoring with polling)
├── data/
│ ├── api-costs.json (cost tracking data)
│ ├── oauth-tokens.json (OAuth tokens — chmod 600)
│ ├── watchlist.json (accounts to monitor)
│ ├── exports/ (saved research)
│ ├── snapshots/ (follower/following snapshots for diff)
│ └── cache/ (auto-managed)
└── references/
└── x-api.md (X API endpoint reference)
Package API Tools
The Package API provides agent memory package management:
| Tool | Purpose | Auth |
|---|---|---|
xint_package_create |
Create ingest job from topic query | XINT_PACKAGE_API_KEY |
xint_package_status |
Get package metadata + freshness | XINT_PACKAGE_API_KEY |
xint_package_query |
Query packages, return claims + citations | XINT_PACKAGE_API_KEY |
xint_package_refresh |
Trigger new snapshot | XINT_PACKAGE_API_KEY |
xint_package_search |
Search package catalog | XINT_PACKAGE_API_KEY |
xint_package_publish |
Publish to shared catalog | XINT_PACKAGE_API_KEY |
Workflow:
xint_package_create-> creates package with topic query + sourcesxint_package_status-> poll until status is "ready"xint_package_query-> retrieve claims with citationsxint_package_refresh-> trigger re-ingest when data is stalexint_package_publish-> share to catalog when quality is confirmed
Agent Patterns
Token Budget Awareness
- Use
--quickflag for initial discovery (1 page, 1hr cache, noise filter) - Use
--fields id,text,metrics.likesto reduce response size - Prefer
xint_searchwithlimit: 5for quick checks - Use
xint_coststo check budget before expensive operations
Batch Operations
- Search + profile in sequence, not parallel (rate limit: 350ms between requests)
- Use
xint_watchfor polling instead of repeated searches - Combine
xint_reportfor topic intelligence instead of multiple searches
Context Window Management
xint_searchwith limit=15: ~3KB responsexint_profilewith count=20: ~4KB responsexint_article: 1-10KB depending on article lengthxint_trends: ~2KB response- Use
--fieldsflag to reduce output to only needed fields
Error Recovery Matrix
| Error Code | Retryable | Agent Action | Example |
|---|---|---|---|
RATE_LIMITED |
Yes | Wait retry_after_ms, then retry |
429 from X API |
AUTH_FAILED |
No | Stop, report missing credential | Missing X_BEARER_TOKEN |
NOT_FOUND |
No | Skip resource, try alternative | Deleted tweet |
BUDGET_DENIED |
No | Stop, use xint costs budget set N |
Daily limit exceeded |
POLICY_DENIED |
No | Stop, escalate to user | Need --policy=engagement |
VALIDATION_ERROR |
No | Fix parameter, retry | Invalid tweet_id format |
TIMEOUT |
Yes | Retry after 5s | Network timeout |
API_ERROR |
If 5xx | Retry after 30s for 5xx, stop for 4xx | X API outage |
Fallback Chain
When a tool fails, try the next option:
xint_search(X API v2, fast, real-time)xint_xsearch(xAI Grok search, AI-enhanced, requires XAI_API_KEY)- Cached results from previous searches (15min TTL)
For article fetching:
xint_articlewith tweet URL (extracts inline X Article)xint_articlewith article URL (web fetch)xint_searchfor tweets about the topic