# Xint

> >

- **Type:** Skill
- **Install:** `agentstack add skill-0xnyk-xint-xint`
- **Verified:** Pending review
- **Seller:** [0xNyk](https://agentstack.voostack.com/s/0xnyk)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [0xNyk](https://github.com/0xNyk)
- **Source:** https://github.com/0xNyk/xint
- **Website:** https://clawhub.ai/0xNyk/xint

## Install

```sh
agentstack add skill-0xnyk-xint-xint
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```bash
# Set your environment variables
export X_BEARER_TOKEN="your-token"
```

### Search

```bash
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:**
```bash
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

```bash
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

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

Fetches full conversation thread by root tweet ID.

### Single Tweet

```bash
bun run xint.ts tweet  [--json]
```

### Article (Full Content Fetcher)

```bash
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:**
```bash
# 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

```bash
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

```bash
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

```bash
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

```bash
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:**
```bash
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)

```bash
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:**
```bash
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)

```bash
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:

```bash
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:

```bash
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:

```bash
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

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

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

**Examples:**
```bash
bun run xint.ts reposts 1234567890
bun run xint.ts reposts 1234567890 --limit 50 --json
```

### User Search

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

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

**Examples:**
```bash
bun run xint.ts users "AI researcher"
bun run xint.ts users "solana developer" --limit 10 --json
```

### Watch (Real-Time Monitoring)

```bash
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:**
```bash
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)

```bash
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:**
```bash
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](https://github.com/0xNyk)
- **Source:** [0xNyk/xint](https://github.com/0xNyk/xint)
- **License:** MIT
- **Homepage:** https://clawhub.ai/0xNyk/xint

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-0xnyk-xint-xint
- Seller: https://agentstack.voostack.com/s/0xnyk
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.