# Twitter Connector

> Search Twitter/X using local Playwright automation with saved cookies (no API key). Use this skill whenever the user asks to find tweets, trending posts, public reactions, or latest discussions on X/Twitter for any topic, including phrasing like “search X”, “find tweets about…”, “what are people saying on Twitter”, “top tweets”, or “recent tweets”. Also use it when the user wants tweet results returned as structured JSON for downstream analysis, or wants tweet detail by a tweet URL.

- Skill: `shellydeng08/twitter-connector` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add shellydeng08/twitter-connector`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shellydeng08/twitter-connector/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: ShellyDeng08 (https://skillmd.com/u/shellydeng08)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shellydeng08/twitter-connector

---


# Twitter Connector

Use this skill to run lightweight Twitter/X search and tweet-detail retrieval from this project.

## What this skill does

- Performs Twitter/X search via Playwright browser automation
- Supports tweet detail retrieval by tweet URL
- Reuses saved login cookies from `scripts/twitter_cookies.json`
- Returns tweet results in JSON (good for follow-up analysis)

## Workflow

1. Dependency check is built-in (auto detect + auto install):
   - `scripts/login.py` and `scripts/search.py` will automatically detect missing `playwright`
   - If missing, they will auto-run install for `playwright` and Chromium browser
   - So you can run commands directly without manual dependency setup

2. If cookie file is missing or expired, run login first:

```bash
python3 scripts/login.py
```

3. Run keyword search or tweet detail:

```bash
python3 scripts/search.py "QUERY" --limit 10 --sort top --json-only
python3 scripts/search.py --url "https://x.com/jack/status/20" --json-only
```

## Search/detail parameters

- `QUERY` (optional): search phrase, or a tweet URL (`https://twitter.com/{user}/status/{id}` / `https://x.com/{user}/status/{id}`)
- `--url` (optional): explicit tweet URL for detail mode
- `--limit` (optional): number of tweets to return in search mode (default 10, clamped to 1-50)
- `--sort` (optional): `top` (engagement-focused) or `live` (latest), search mode only
- `--json-only` (optional): prints only the JSON array (best for machine parsing)

## Example commands

```bash
python3 scripts/search.py "Claude Code" --limit 8 --sort top --json-only
python3 scripts/search.py "AI agent framework" --limit 10 --sort live --json-only
python3 scripts/search.py --url "https://x.com/jack/status/20" --json-only
python3 scripts/search.py "https://twitter.com/jack/status/20" --json-only
```

## Output shape

Each tweet entry includes:

- `text`
- `user`
- `time`
- `likes`
- `retweets`
- `replies`
- `link`

Output is always a JSON array:
- Search mode: up to `--limit` items
- Detail mode: one item when successful, otherwise `[]`

## Usage boundaries

- Keep usage light (personal/manual exploration)
- If login state expires, re-run `scripts/login.py`
- Don’t use this workflow for mass scraping