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

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.

• 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 # 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 mygroup --since 1d

Last week from all groups

bun run ~/.claude/skills/twitter/x-search/x-search.ts feed all --since 7d

Custom accounts (comma-separated)

bun run ~/.claude/skills/twitter/x-search/x-search.ts feed user1,user2,user3 --since 1d

Free via bird CLI (no API cost)

bun run ~/.claude/skills/twitter/x-search/x-search.ts feed mygroup --since 1d --bird

Save as markdown research doc

bun run ~/.claude/skills/twitter/x-search/x-search.ts feed mygroup --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 mygroup # 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 karpathy "AI research" bun run ~/.claude/skills/twitter/x-search/x-search.ts feedgroup remove tech karpathy 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 tech,news

Groups stored at ~/.claude/skills/twitter/x-search/data/feedgroups.json . Ships empty — populate with your own accounts.

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.

Posting

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

Reading

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

Search (free, via GraphQL)

bird search "query" -n 10 bird search "from:anthropic" -n 20 --json

Monitoring

bird mentions -n 10 bird bookmarks -n 20 bird likes -n 20 bird following -n 50 bird followers -n 50

Maintenance

bird whoami # verify auth bird check # credential sources bird query-ids --fresh # refresh when Twitter rotates IDs

Smaug — Bookmark Archival

Archives bookmarks/likes to organized markdown with AI categorization.

cd ~/tools/smaug npx smaug run # fetch + process with Claude npx smaug fetch 20 # fetch only npx smaug fetch --source likes # likes instead of bookmarks npx smaug run -t # track token costs npx smaug status # check state

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

Daily feed from followed accounts x-search feed Cheap batched OR-query, grouped output

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