| name | twitter |
| description | Search, post, monitor, and archive on Twitter/X via three modes: official API v2 search via x-search (pay-per-use, $0.005/read), session-based posting/reading via bird CLI (free, browser cookies), and bookmark archival via Smaug. Triggers on 'search tweets', 'post to X', 'monitor account', 'archive bookmarks', 'research topic on 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.
echo 'X_BEARER_TOKEN=your_token_here' >> ~/.claude/skills/twitter/.env
export X_BEARER_TOKEN=your_token_here
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.
- Go to console.x.com → your project → Keys and tokens
- Under "Consumer Keys", copy API Key and API Key Secret
- Under "Authentication Tokens", generate Access Token and Access Token Secret (with Read and Write permissions)
- 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
bird whoami
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
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).
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed geopolitics --since 1d
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed all-feeds --since 7d
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed imetatronink,Megatron_ron --since 1d
bun run ~/.claude/skills/twitter/x-search/x-search.ts feed geopolitics --since 1d --bird
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
bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup show geopolitics
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
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
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).
bun run ~/.claude/skills/twitter/x-search/x-search.ts post "Hello from x-search!"
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 "query" -n 10
bird --cookie-source chrome search "from:anthropic" -n 20 --json
Monitoring
bird --cookie-source chrome mentions -n 10
bird --cookie-source chrome bookmarks -n 20
bird --cookie-source chrome likes -n 20
bird --cookie-source chrome following -n 50
bird --cookie-source chrome followers -n 50
Maintenance
bird --cookie-source chrome whoami
bird --cookie-source chrome check
bird --cookie-source chrome query-ids --fresh
Smaug — Bookmark Archival
Archives bookmarks/likes to organized markdown with AI categorization.
cd ~/tools/smaug
npx smaug run
npx smaug fetch 20
npx smaug fetch --source likes
npx smaug run -t
npx smaug status
Output: bookmarks.md, knowledge/tools/, knowledge/articles/
Research Methodology
For deep X research, follow this agentic loop:
- Decompose — Break topic into 2-3 search queries targeting different angles
- Search — Run each query with
--quick first to assess signal quality
- Refine — Narrow queries based on initial results (add
--from, --quality, --since)
- Thread — Follow high-value conversation threads for deeper context
- Deep-Dive — Re-run best queries with
--pages 3 --markdown --save
- Synthesize — Compile findings from saved markdown into analysis
Default to --quick for exploratory queries. Use full mode only for confirmed-valuable searches.
Troubleshooting
x-search: "X_BEARER_TOKEN not found"
Set token via env, ~/.config/env/global.env, or ~/.claude/skills/twitter/.env. Get one at console.x.com.
bird: 403 Errors
Browser cookies expired. Log into Twitter in browser, then bird check.
bird: Query ID Errors
Twitter rotated internals. Run bird query-ids --fresh.
Rate Limiting (429)
Wait for reset. x-search shows reset time. bird: wait a few minutes.
When to Use Which
| Task | Tool | Why |
|---|
| Search tweets by topic | x-search | Official API, cost-tracked, cached |
| Research a topic deeply | x-search | Multi-page, markdown output, save |
| Monitor specific accounts | x-search watchlist | Batch check with cost tracking |
| Post a tweet or reply | x-search post/reply | Official API, reliable, $0.01/post |
| Post with media | bird | Free, media upload support |
| Read a specific tweet/thread | bird (free) or x-search (tracked) | bird for quick reads, x-search for research |
| Check mentions | bird | Free, real-time |
| Archive bookmarks | smaug | AI categorization, markdown output |
| Fetch bookmarks/likes | bird + smaug | Session-based access |