x

X (Twitter)

Skill Directory

<SKILL_DIR> is the directory containing this SKILL.md file. To find it, look at the path where this skill was loaded from. It is typically ~/.claude/skills/x (installed) or wherever this file lives. Determine it ONCE at the start and reuse it.

Setup (run FIRST — every time, before any operation)

You MUST complete this setup before running any script. Do NOT skip this step.

sig status x 2>&1

Check the JSON output fields configured and valid:

• configured: false → run Provider Setup below. Do NOT proceed without completing it.
• valid: false (but configured: true) → run sig login x, then re-check.
• valid: true → detect proxy (see below), then execute the user's request.

Provider Setup

1. Read <SKILL_DIR>/references/provider-config.yaml
2. Append the provider block to ~/.sig/config.yaml under providers:
3. Ask the user: "Do you need a proxy to access this site?" — if yes, add networkProxy: <url> under the provider in config.yaml
4. Run sig login x (with --network-proxy <url> if proxy was specified)
5. Verify: run sig status x again — must show valid: true before proceeding

Proxy Detection (after provider is valid)

grep -A15 "^\s*x:" ~/.sig/config.yaml | grep networkProxy | awk '{print $2}'

If this outputs a URL, prefix ALL python3 commands with HTTPS_PROXY=<url> HTTP_PROXY=<url>. If using socks5, convert to socks5h for python (e.g. socks5://... → socks5h://...). If empty, no proxy needed.

Running Scripts

All scripts require setup to be completed first (see above).

---

Scripts Reference

Read Operations

Script	Purpose	Args
x_user.py	User profile	--username NAME
x_tweets.py	User's tweet timeline	--username NAME [--limit N]
x_tweet.py	Single tweet + thread	--id ID_OR_URL [--limit N]
x_search.py	Search tweets	--query TEXT [--limit N] [--type top|latest]
x_trending.py	Trending topics	[--limit N]
x_followers.py	Followers or following	--username NAME [--limit N] [--mode followers|following]

Write Operations

Script	Purpose	Args
x_post.py	Create a tweet	--cookie COOKIE --text TEXT [--reply-to ID]
x_delete.py	Delete a tweet	--cookie COOKIE --id ID_OR_URL
x_like.py	Like or unlike	--cookie COOKIE --id ID_OR_URL [--undo]
x_retweet.py	Retweet or unretweet	--cookie COOKIE --id ID_OR_URL [--undo]
x_follow.py	Follow or unfollow	--cookie COOKIE --username NAME [--undo]
x_bookmark.py	Bookmark or unbookmark	--cookie COOKIE --id ID_OR_URL [--undo]

---

Command Examples

All examples assume you've cd'd into <SKILL_DIR> and set proxy if needed.

Search tweets

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_search.py --query "Claude AI" --type top --limit 10'

View user profile

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_user.py --username elonmusk'

Read recent tweets

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_tweets.py --username elonmusk --limit 10'

Read a tweet thread

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_tweet.py --id "https://x.com/user/status/12345678"'

Post a tweet (ALWAYS confirm with user first)

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_post.py --cookie "$SIG_X_COOKIE" --text "Hello from sigcli!"'

Reply to a tweet

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_post.py --cookie "$SIG_X_COOKIE" --text "Great point!" --reply-to 2050336207561724307'

Delete a tweet (confirm with user first — irreversible)

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_delete.py --cookie "$SIG_X_COOKIE" --id 2050417089987711033'

Like / unlike

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_like.py --cookie "$SIG_X_COOKIE" --id 12345'
sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_like.py --cookie "$SIG_X_COOKIE" --id 12345 --undo'

Follow / unfollow

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_follow.py --cookie "$SIG_X_COOKIE" --username elonmusk'
sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_follow.py --cookie "$SIG_X_COOKIE" --username elonmusk --undo'

Bookmark / unbookmark

sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_bookmark.py --cookie "$SIG_X_COOKIE" --id 12345'
sig run x -- bash -c 'cd <SKILL_DIR> && python3 scripts/x_bookmark.py --cookie "$SIG_X_COOKIE" --id 12345 --undo'

---

Safety Rules

1. ALWAYS show tweet text to user and get explicit confirmation before posting. Tweets are public.
2. Tweets and replies must be ≤ 280 characters. Check length before posting. URLs count as ~23 characters (t.co shortening). If the text exceeds 280 characters, shorten it or split into a thread.
3. Like, retweet, follow, bookmark are reversible — use --undo to reverse.
4. Delete is irreversible — confirm with user before deleting.

---

Error Recovery

When a command fails, follow this decision tree:

Error	Meaning	Action
ConnectionError	Can't reach x.com	Ask user for proxy URL, then retry with HTTPS_PROXY=<url>
Timeout	Network too slow	Retry once. If still fails, check proxy.
AUTH_REQUIRED / 401	Cookie missing or expired	Auto-run sig login x (do NOT ask user), then retry the failed command.
HTTP_403	IP blocked or query IDs stale	Retry once (auto-refresh kicks in). If still 403, change proxy or wait.
HTTP_429	Rate limited	Wait 30 seconds, then retry.
NOT_FOUND	User/tweet doesn't exist	Verify the ID or username with the user.
POST_FAILED	Tweet creation failed	Show error details to user. May be duplicate or policy violation.
Query ID / GraphQL error	Stale query IDs, refresh failed	Clear cache (restart script), retry. If persistent, bundles changed.

Key principle: if ANY command fails on first run, do NOT silently proceed. Diagnose using this table, fix the issue, and re-validate before continuing with the user's request.

---

Technical Notes

• Query ID caching: Query IDs are cached to a file (scripts/.query_id_cache.json) so they persist across script calls. First script invocation fetches from X's JS bundles (~3s), all subsequent calls within 1 hour read from disk instantly. The file auto-refreshes when the TTL expires.
• Transaction ID: X requires x-client-transaction-id header. Generated automatically using the XClientTransaction library.
• Pagination: Timeline endpoints paginate internally (up to 5 pages).
• Cookie TTL: Cookies typically last 7 days. After that, re-authenticate.