/xint

name: xint
description: >
  X Intelligence CLI for searching, monitoring, and analyzing X/Twitter from the terminal.
  Use for X/Twitter research prompts such as "search x", "find tweets about", "what's X saying",
  trend checks, follower diffs, real-time watch tasks, sentiment/report analysis, and bookmark-sync workflows.
  Best when recent community discourse matters (library/API changes, launches, market or cultural events).
  Supports search, watch, trends, bookmarks, likes/following (OAuth), Grok analysis, and JSON/JSONL/CSV/Markdown export.
  Non-goals: posting original tweets, DMs, or enterprise-only features.
credentials:
  - name: X_BEARER_TOKEN
    description: X API v2 bearer token for search, profile, thread, tweet, trends
    required: true
  - name: XAI_API_KEY
    description: xAI API key for Grok analysis, article fetching, sentiment, x-search, collections
    required: false
  - name: XAI_MANAGEMENT_API_KEY
    description: xAI Management API key for collections management
    required: false
  - name: X_CLIENT_ID
    description: X OAuth 2.0 client ID for user-context operations (bookmarks, likes, following, diff)
    required: false
required_env_vars:
  - X_BEARER_TOKEN
primary_credential: X_BEARER_TOKEN
security:
  always: false
  autonomous: false
  local_data_dir: data/
  fs_write:
    - path: data/cache/
      why: search/profile/trends response cache (15min TTL)
    - path: data/exports/
      why: saved research output (--save flag only)
    - path: data/snapshots/
      why: follower/following snapshots for diff
    - path: data/oauth-tokens.json
      why: OAuth tokens (chmod 600)
    - path: data/api-costs.json
      why: cost tracking
    - path: data/watchlist.json
      why: monitored accounts
    - path: data/credits.json
      why: Grok credit tracking
    - path: data/bookmark-kb.json
      why: bookmark knowledge base index
    - path: ~/obsidian/nyk/inbox/
      why: Obsidian bookmark sync only — opt-in, only when user explicitly requests it
  network_endpoints:
    - https://api.x.com
    - https://x.com
    - https://api.x.ai

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

• `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 "<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 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