/x-twitter

name: x-twitter
description: "Post to X via a signed-in browser session (live method — no API keys); API v2 path for search/read/engagement."

X (Twitter)

Post, search, read, and monitor X from the command line.

When to use

The user wants to **post to / read from X (Twitter)** — publish a tweet or thread, reply, search recent tweets, check mentions/timeline, or pull engagement on a known tweet id. Not for other social platforms.

Failure modes

• **403 / "not permitted"** on post → the X API tier doesn't allow writes, or the

app lacks Read+Write permission (regenerate the access token AFTER setting RW).

• **429 rate-limited** → API v2 free tier has low write/read caps; back off and retry later, don't loop.
• **401** → a key in `.env` is missing or stale. The skill uses five: `X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET`, and `X_BEARER_TOKEN`. **Reads authenticate with the bearer token**, so a 401 on search/mentions/timeline is most often a stale `X_BEARER_TOKEN`, not the OAuth pair.
• **Done =** the command prints the new tweet id / the result rows; a post with no id back did not publish.

Usage

Posting — use the browser session (live method)

The OAuth1 API post path below is **NOT wired** on this fleet: posting needs 4 write keys (X_API_KEY/SECRET + X_ACCESS_TOKEN/SECRET) that are not in the vault. Posting is NOT credit-gated — it just needs those keys, which we don't have. **Do not conclude "X is blocked."** The working path is a signed-in Chrome-for-Testing browser session:

# Is the profile signed in?  (headless, exit 0 = yes, 2 = no)
node skills/x-twitter/x-post-browser.mjs check

# Owner signs in once (headed GUI window; email/phone — Google/Apple OAuth stay blocked)
node skills/x-twitter/x-post-browser.mjs login

# Compose only, screenshot, DO NOT publish  (always run this first)
node skills/x-twitter/x-post-browser.mjs post "Your tweet text" --dry-run

# Publish  (only after owner OKs the dry-run)
node skills/x-twitter/x-post-browser.mjs post "Your tweet text"

• Profile: `<workspace>/data/x-browser-profile`, resolved through `scripts/sutando-config.sh workspace`

(override with `$X_BROWSER_PROFILE`, declared in this skill's `manifest.json`). Per-host, holds live session cookies, and never synced — `data/` is in the vault `exclude` list. A profile still sitting at the pre-#2133 location is used with a one-line notice until you move it, so upgrading does not cost you a fresh sign-in. `$X_LOGIN_DONE_SENTINEL` and `$X_LOGIN_TIMEOUT_ITERS` are declared alongside it but are test/CI controls — there is no reason to set them by hand. Sign-in survives ONLY because `check`/`post` strip Playwright's `--use-mock-keychain` so cookies decrypt with the real login keychain — see `memory/reference_x_browser_signin_oauth_blocked_use_email_phone.md`.

• **Always `--dry-run` first and confirm with the owner before publishing.** Nothing

posts without an explicit OK.

API v2 usage (search / read / engagement — reads only, no post keys)

# Post
python3 skills/x-twitter/x-post.py post "Your tweet text"
python3 skills/x-twitter/x-post.py post "With video" --media /path/to/video.mp4
python3 skills/x-twitter/x-post.py post --reply-to 123456789 "Reply text"

# Search
python3 skills/x-twitter/x-post.py search "sutando agent"
python3 skills/x-twitter/x-post.py search "from:Chi_Wang_" --limit 5

# Read a tweet
python3 skills/x-twitter/x-post.py read 2040817066199195818

# Mentions & your own timeline (OAuth1 — resolves users/me)
python3 skills/x-twitter/x-post.py mentions
python3 skills/x-twitter/x-post.py timeline

# ANOTHER account's timeline (bearer only — no OAuth1 needed)
python3 skills/x-twitter/x-post.py user-timeline Chi_Wang_
python3 skills/x-twitter/x-post.py user-timeline Chi_Wang_ --limit 100 --exclude retweets,replies

# Engagement (likes, retweets, views)
python3 skills/x-twitter/x-post.py engagement 2040817066199195818

Which auth each command needs

`search`, `read` and `user-timeline` run on **`X_BEARER_TOKEN` alone** — app-only auth, stdlib urllib, no `requests`/`requests_oauthlib` install. `post`, `mentions` and `timeline` need the OAuth1 four (`X_API_KEY`, `X_API_SECRET`, `X_ACCESS_TOKEN`, `X_ACCESS_TOKEN_SECRET`).

**`timeline` vs `user-timeline` is an auth distinction, not a scope one.** `timeline` resolves `users/me`, which is OAuth1-only; `user-timeline` takes a handle and reads the same endpoint (`users/{id}/tweets`) over bearer. On a bearer-only host `timeline` cannot run and `user-timeline` can.

**`--limit` is 5..100 on `user-timeline`** — this endpoint's own bound. `search` rejects below 10; different endpoints, different bounds. Outside the range the command refuses locally (rc=2) rather than letting X return a 400 that reads like an account problem.

**`--exclude replies` keeps self-replies.** X drops replies to *others* and retains an author's own thread continuations, so `--exclude retweets,replies` can still return a tweet whose `in_reply_to_user_id` is the author. Measured, not assumed.

Setup

1. Install Python dependencies (one-time):

   pip3 install requests requests-oauthlib

2. Go to https://developer.x.com and sign in 3. Create a Project + App 4. Generate keys and add to `.env`:

   X_API_KEY=...
   X_API_SECRET=...
   X_ACCESS_TOKEN=...
   X_ACCESS_TOKEN_SECRET=...

Notes

• Free tier: 500 posts/month, search recent tweets (7 days)
• Video upload uses chunked upload (supports 4K)
• Always confirm post content with user before publishing