twitter

Twitter/X — Dual-Mode Integration

Three tools for different operations. Choose by task:

| Mode | Tool | Auth | Cost | Use For | |------|------|------|------|---------| | Official API | x-search | Bearer token | $0.005/read, $0.01/user | Search, research, profiles, threads, monitoring | | Official API | x-search post/reply | OAuth 1.0a | $0.01/post | Posting, replying via official API | | Session | bird | Browser cookies | Free | Posting, replying, bookmarks, mentions, media | | Archival | smaug | Via bird | Free | Bookmark/likes processing, AI-powered filing |

Alternative: opencli twitter provides 25 free session-based commands (post, reply, search, bookmarks, follow, block, etc.) via Chrome session reuse. Prefer opencli for routine Twitter operations. Use x-search for deep research with cost tracking. bird CLI remains available as fallback.

Setup

x-search (Official API v2)

Requires an X API Bearer token from console.x.com. Pay-per-use — no monthly commitment.

# Store token (pick one)
echo 'X_BEARER_TOKEN=your_token_here' >> ~/.claude/skills/twitter/.env
# OR
export X_BEARER_TOKEN=your_token_here
# OR
mkdir -p ~/.config/env && echo 'X_BEARER_TOKEN=your_token_here' >> ~/.config/env/global.env

OAuth 1.0a (for posting)

Posting requires OAuth 1.0a credentials in addition to the Bearer token.

1. Go to console.x.com → your project → Keys and tokens
2. Under "Consumer Keys", copy API Key and API Key Secret
3. Under "Authentication Tokens", generate Access Token and Access Token Secret (with Read and Write permissions)
4. Add all four to ~/.claude/skills/twitter/.env:

X_API_KEY=your_api_key
X_API_SECRET=your_api_secret
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret

bird CLI

brew install steipete/tap/bird   # or: npm install -g @steipete/bird
bird whoami                       # verify auth (uses browser cookies)

Smaug (archival)

cd ~/tools/smaug && npx smaug setup

x-search — Official API Research

Run via: bun run ~/.claude/skills/twitter/x-search/x-search.ts <command>

Quick Search (cost-conscious default)

bun run ~/.claude/skills/twitter/x-search/x-search.ts search "AI agents" --quick
# 1 page, max 10 results, auto noise filter, 1hr cache, cost summary
# Est. cost: ~$0.50

Full Search

bun run ~/.claude/skills/twitter/x-search/x-search.ts search "Claude Code" --pages 3 --sort likes --since 1d
bun run ~/.claude/skills/twitter/x-search/x-search.ts search "BG3 mods" --from LarianStudios --quality
bun run ~/.claude/skills/twitter/x-search/x-search.ts search "Minoan archaeology" --markdown --save

Search Options

| Flag | Default | Description | |------|---------|-------------| | --quick | off | 1 page, max 10, noise filter, 1hr cache | | --sort | likes | likes\|impressions\|retweets\|recent | | --since | 7d | 1h\|3h\|12h\|1d\|7d or ISO timestamp | | --pages | 1 | 1-5 pages (100 tweets/page) | | --limit | 15 | Max results displayed | | --from | — | Shorthand for from:username | | --quality | off | Filter tweets with < 10 likes | | --min-likes | 0 | Minimum like threshold | | --no-replies | off | Exclude replies | | --save | off | Save markdown to ~/tools/smaug/knowledge/research/ | | --json | off | Raw JSON output | | --markdown | off | Markdown research document |

Profiles, Threads, Single Tweets

bun run ~/.claude/skills/twitter/x-search/x-search.ts profile AnthropicAI --count 10
bun run ~/.claude/skills/twitter/x-search/x-search.ts thread 1234567890 --pages 3
bun run ~/.claude/skills/twitter/x-search/x-search.ts tweet 1234567890

Feed -- Daily Reading from Followed Accounts

Pull the latest tweets from named account groups, filtered by time window. Uses batched OR-query search (cheap, ~$0.005/tweet).

# Read today's tweets from a feed group
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed geopolitics --since 1d

# Last week from all groups
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed all-feeds --since 7d

# Custom accounts (comma-separated)
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed imetatronink,Megatron_ron --since 1d

# Free via bird CLI (no API cost)
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed geopolitics --since 1d --bird

# Save as markdown research doc
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed all-feeds --since 7d --markdown --save

Feed options: --since 1d|7d|1h|3h|12h, --limit N (tweets per account, default 4), --bird (free), --markdown, --save, --json, --no-cache.

Feed Groups -- Named Account Collections

bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup                              # list all
bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup show geopolitics              # show group
bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup create tech "Tech follows"
bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup add tech kaboreas "K8s/infra"
bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup remove tech kaboreas
bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup delete tech
bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup alias daily geopolitics,palestine

Pre-configured groups: geopolitics (18 accounts), palestine (3 accounts), alias all-feeds (all 21). Stored at ~/.claude/skills/twitter/x-search/data/feedgroups.json.

Watchlist

Monitor accounts with batch checking (uses profile API, more expensive).

bun run ~/.claude/skills/twitter/x-search/x-search.ts watchlist                    # show list
bun run ~/.claude/skills/twitter/x-search/x-search.ts watchlist add kikismith "Ancient art"
bun run ~/.claude/skills/twitter/x-search/x-search.ts watchlist remove kikismith
bun run ~/.claude/skills/twitter/x-search/x-search.ts watchlist check              # check all accounts

Watchlist stored at ~/.claude/skills/twitter/x-search/data/watchlist.json.

Posting and Replying (OAuth 1.0a)

Post tweets and replies via the official API. Requires OAuth 1.0a credentials (see setup above).

# Post a tweet
bun run ~/.claude/skills/twitter/x-search/x-search.ts post "Hello from x-search!"

# Reply to a tweet
bun run ~/.claude/skills/twitter/x-search/x-search.ts reply 1234567890 "Great thread!"

• 280-character limit enforced
• Cost: $0.01 per post
• Returns the posted tweet URL
• Errors: descriptive messages for missing credentials, permission issues, rate limits

Cache

15-minute TTL (1hr in quick mode). File-based, auto-managed.

bun run ~/.claude/skills/twitter/x-search/x-search.ts cache clear

Cost Reference

| Resource | Cost | |----------|------| | Post read | $0.005 | | User lookup | $0.010 | | Post create | $0.010 | | Quick search (~100 tweets) | ~$0.50 | | 3-page deep search (~300 tweets) | ~$1.50 | | Profile check | ~$0.51 | | Cached repeat | FREE |

X API deduplicates reads within 24h. Cache prevents redundant queries within 15min.

bird CLI — Session-Based Operations

Uses undocumented Twitter GraphQL APIs via browser cookies. Free but may break when Twitter rotates internals.

Always pass --cookie-source chrome to all bird commands to avoid EPERM warnings from Safari cookie access.

Posting

bird --cookie-source chrome tweet "Hello world"
bird --cookie-source chrome reply 123456789 "Great thread!"
bird --cookie-source chrome tweet "With image" --media photo.png --alt "Description"

Reading

bird --cookie-source chrome read 123456789
bird --cookie-source chrome thread https://x.com/user/status/123456789
bird --cookie-source chrome replies 123456789 --json

Search (free, via GraphQL)

bird --cookie-source chrome search "q