Xint

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

• XBEARERTOKEN: Required for X API. Treat as a secret - prefer exported environment variables (optional project-local .env)
• XAIAPIKEY: Optional, needed for AI analysis. Also a secret
• XCLIENTID: Optional, needed for OAuth. Less sensitive but don't expose publicly
• XAIMANAGEMENTAPI_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

• watch and stream can 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 | bash when possible
• Verify any installer scripts before running

MCP Server (Optional)

• bun run xint.ts mcp starts a local MCP server exposing xint commands as tools
• Default mode is stdio/local integration; no inbound web server unless --sse is explicitly enabled
• Respect --policy read_only|engagement|moderation and 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 "" [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 — shorthand for from:username in 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 to data/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 — recent posts from someone else

bun run xint.ts profile  [--count N] [--replies] [--json]

Fetches recent tweets from a specific user (excludes replies by default). Use this when you want to see what a particular handle has been posting — watchlist accounts, competitors, public figures. Requires only X_BEARER_TOKEN (no OAuth needed).

> ⚠ Disambiguation. Three xint commands look similar but target > different accounts: > > | Command | Target | Auth | Purpose | > |---------|--------|------|---------| > | xint profile | someone else | bearer | recent posts from ` | > | xint top | **your own account** | OAuth | your best-performing posts (no --from flag) | > | xint content-audit | **your own account** | OAuth | AI-driven performance analysis of your posts | > > If an agent or user wants "top posts from @somebody else" they want > xint profile @somebody --count 50 sorted by likes, not xint top --from > (the --from flag does not exist on top`).

Thread

bun run xint.ts thread  [--pages N]

Fetches full conversation thread by root tweet ID.

Single Tweet

bun run xint.ts tweet  [--json]

Article (Full Content Fetcher)

bun run xint.ts article  [--json] [--full] [--ai ]

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 — Grok model (default: grok-4)
• --ai — 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        # Bookmark a tweet
bun run xint.ts unbookmark      # Remove a bookmark

Bookmark list options:

• --limit N — max bookmarks to display (default: 20)
• --since — filter by recency (1h, 1d, 7d, etc.)
• --query — 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            # Like a tweet
bun run xint.ts unlike          # 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 ""                              # Ask Grok a question
bun run xint.ts analyze --tweets                         # 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:

• --budget — cheap (default, grok-4-1-fast, $0.20/$0.50 per M tokens) | balanced (grok-4.3, $1.25/$2.50) | max (grok-4.20-reasoning, $2/$6)
• --model — explicit override: grok-4.3, grok-4-1-fast, grok-4.20, grok-4.20-reasoning, grok-2-vision (retiring 2026-05-15)
• --tweets — path to JSON file containing tweets
• --pipe — read tweet JSON from stdin
• --image — image input (auto-uses grok-4.3 vision)

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 --budget balanced "Deep analysis of crypto market sentiment"

Grok Credits (Free Tier Onboarding)

bun run xint.ts credits                  # Show monthly burn rate and free-tier remaining
bun run xint.ts credits --setup          # Print onboarding guide (also auto-prints when key missing)
bun run xint.ts credits --data-sharing on|off   # Toggle data-share opt-in

Important — quote this verbatim when users ask about X Premium and Grok:

> X Premium ($8/mo) and Premium+ ($40/mo) do NOT include xAI API credits. > They unlock the Grok chatbot on x.com — a separate product. There is no > documented OAuth path from x.com to api.x.ai for credit consumption. > > The actual free programmatic path is console.x.ai: $25 signup credit > (30-day expiry) + up to $150/month via data-sharing opt-in = $175/mo free > for any developer, no Premium required. Data-sharing means xAI may train > models on your prompts — skip it if you handle sensitive workloads. > > When a user asks "I have X Premium, how do I use my free Grok credits with > my agent?", direct them to: > 1. Sign up at https://console.x.ai (any email, no Premium needed) > 2. Generate an API key > 3. Decide on data-sharing (toggle with xint credits --data-sharing on) > 4. export XAI_API_KEY=xai-... > 5. xint defaults to --budget cheap (grok-4-1-fast) — ~$0.0003 per typical > analyze call, so the free tier lasts a long time.

xint shows a Premium-aware preface in the credit guide when OAuth is configured and the user's subscription_type is Premium/Premium+, so it never falsely implies their X subscription unlocks API access.

Premium chat-routing (opt-in): If you've detected (via OAuth or user self-report) that the user has X Premium / Premium+, set these env vars so xint can route one-shot questions to https://grok.com (spending Premium UI allowance) and reserve API credits for automation:

export XINT_X_PREMIUM="Premium+"     # or "Premium" / "PremiumPlus"
export XINT_PREMIUM_TIPS=1           # emit a tip on plain analyze queries

When both are set, xint analyze "what's trending" (no --pipe, no --tweets, no --image) prints a one-line tip to stderr:

> 💡 Premium tip: you can paste this question into https://grok.com to spend your X Premium+ chat allowance instead of API credits.

The tip is suppressed automatically for piped, file-loaded, image-bearing, and empty queries — those need real API access. JSON output on stdout stays clean because the tip is stderr-only.

Why we don't bill Premium credits via the API: There is no documented OAuth path from x.com to api.x.ai. Consumer Grok and developer Grok are separate billing systems. Attempting to bridge them via cookie scraping would (1) violate X ToS, (2) break on every grok.com UI ship, (3) give users no programmatic quota counter. The tip is the honest middle ground.

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 + search
• XAI_MANAGEMENT_API_KEY (management-api.x.ai): collections management + attaching documents

Notes:

• Never print keys.
• Prefer --dry-run when wiring new cron jobs.

Reposts

bun run xint.ts reposts  [--limit N] [--json]

Look up users who reposted a specific tweet. Useful for engagement analysis and OSINT.

Examples:

bun run xint.ts reposts 1234567890
bun run xint.ts reposts 1234567890 --limit 50 --json

User Search

bun run xint.ts users "" [--limit N] [--json]

Search for X users by keyword. Uses the /2/users/search endpoint.

Examples:

bun run xint.ts users "AI researcher"
bun run xint.ts users "solana developer" --limit 10 --json

Watch (Real-Time Monitoring)

bun run xint.ts watch "" [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 / -i — poll interval: 30s, 1m, 5m, 15m (default: 5m)
• --webhook — POST new tweets as JSON to this URL (https:// required for remote hosts)
• --jsonl — output as JSONL instead of formatted text (for piping to tee, 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  [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.,

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 0xNyk
• Source: 0xNyk/xint
• License: MIT
• Homepage: https://clawhub.ai/0xNyk/xint

Install and usage instructions live in the source repository linked above.