# twitter-reader

Read-only Twitter/X skill for financial research using [opencli](https://github.com/jackwener/opencli).

## What it does

Reads Twitter/X for financial research — searching market discussions, reading analyst tweets, tracking sentiment, and monitoring financial news. Capabilities include:

- **Home feed / timeline** — read your feed ("For You" or "Following")
- **Search** — find tweets by keyword with relevance or recency filters
- **Trending** — view trending topics for market themes
- **Bookmarks** — view your saved tweets
- **User tweets** — fetch a user's recent posts (chronological)
- **User profiles** — look up users, their followers, and following
- **Tweet threads & articles** — view specific threads and long-form articles
- **Notifications** — read your Twitter notifications

**This skill is read-only.** It does NOT support posting, liking, retweeting, replying, or any write operations.

## Authentication

No API keys needed — opencli reuses your existing Chrome browser session via the Browser Bridge extension. Just be logged into x.com in Chrome.

## Triggers

- "check my feed", "search Twitter for", "show my bookmarks"
- "what are people saying about AAPL", "market sentiment on Twitter"
- "look up @user", "who follows", "fintwit", "what's trending"
- Any mention of Twitter/X in context of financial news or market research

## Platform

Works on **Claude Code** and other CLI-based agents. Does **not** work on Claude.ai — the sandbox restricts network access and binaries required by opencli.

## Setup

```bash
# Choose finance-social-readers when prompted.
npx plugins add himself65/finance-skills

# Or install just this skill
npx skills add himself65/finance-skills --skill twitter-reader
```

See the [main README](../../../../README.md) for more installation options.

## Prerequisites

- Node.js >= 20 (for `npm install -g @jackwener/opencli`)
- Chrome with the [Browser Bridge extension](https://github.com/jackwener/opencli/releases) installed (load unpacked from `chrome://extensions` in Developer mode)
- Logged into x.com in Chrome

## Reference files

- `references/commands.md` — Complete read command reference with all flags, research workflows, and usage examples
- `references/schema.md` — Output format documentation and column definitions

---
name: twitter-reader
description: >
  Read Twitter/X for financial research through opencli: the user's home timeline,
  tweet search, trending topics, bookmarks, a user's recent tweets, threads,
  articles, profiles, followers and following, and notifications. Use this skill
  whenever the user wants to know what people are saying on Twitter/X or fintwit
  about a stock, topic, or market event, check their feed or bookmarks, see what's
  trending, or look up an @account and its posts. Read-only: it cannot post, like,
  retweet, reply, or follow.
---

# Twitter Skill (Read-Only)

If your host has not already executed the shell probes below (for example, in Codex), run the commands inside the `!` wrappers with its shell tool before choosing a setup path. Use the actual output; if shell access is unavailable, report that limitation.

Reads Twitter/X for financial research using [opencli](https://github.com/jackwener/opencli), a universal CLI tool that bridges web services to the terminal via browser session reuse.

**This skill is read-only.** It is designed for financial research: searching market discussions, reading analyst tweets, tracking sentiment, and monitoring financial news on Twitter/X. It does NOT support posting, liking, retweeting, replying, or any write operations.

**Important**: opencli reuses your existing Chrome login session — no API keys or cookie extraction needed. Just be logged into x.com in Chrome and have the Browser Bridge extension installed.

---

## Step 1: Ensure opencli Is Installed and Ready

**Current environment status:**

```
!`(command -v opencli && opencli doctor 2>&1 | head -5 && echo "READY" || echo "SETUP_NEEDED") 2>/dev/null || echo "NOT_INSTALLED"`
```

If the status above shows `READY`, skip to Step 2. If `NOT_INSTALLED`, install first:

```bash
# Install opencli globally
npm install -g @jackwener/opencli
```

If `SETUP_NEEDED`, guide the user through setup:

### Setup

opencli requires Node.js >= 20 and a Chrome browser with the Browser Bridge extension:

1. **Install the Browser Bridge extension:**
   - Download the latest `opencli-extension-v{version}.zip` from the [GitHub Releases page](https://github.com/jackwener/opencli/releases)
   - Unzip it, open `chrome://extensions` in Chrome, and enable **Developer mode**
   - Click **Load unpacked** and select the unzipped folder
2. **Login to x.com** in Chrome — opencli reuses your existing browser session
3. **Verify connectivity:**

```bash
opencli doctor
```

This auto-starts the daemon, verifies the extension is connected, and checks session health.

### Common setup issues

| Symptom | Fix |
|---------|-----|
| `Extension not connected` | Install Browser Bridge extension in Chrome and ensure it's enabled |
| `Daemon not running` | Run `opencli doctor` — it auto-starts the daemon |
| `No session for twitter.com` | Login to x.com in Chrome, then retry |
| `CSRF token missing` | Refresh x.com in Chrome to regenerate the ct0 cookie |

---

## Step 2: Identify What the User Needs

Match the user's request to one of the read commands below, then use the corresponding command from `references/commands.md`.

| User Request | Command | Key Flags |
|---|---|---|
| Setup check | `opencli doctor` | — |
| Home feed / timeline | `opencli twitter timeline` | `--type for-you\|following`, `--limit N` (default 20) |
| Search tweets | `opencli twitter search "QUERY"` | `--filter top\|live`, `--limit N` (default 15) |
| Trending topics | `opencli twitter trending` | `--limit N` (default 20) |
| Bookmarks | `opencli twitter bookmarks` | `--limit N` (default 20) |
| Recent tweets from a user | `opencli twitter tweets USERNAME` | `--limit N` (default 20) |
| View a specific thread | `opencli twitter thread TWEET_ID` | `--limit N` (default 50) |
| Twitter article | `opencli twitter article TWEET_ID` | — |
| User profile | `opencli twitter profile USERNAME` | — (defaults to logged-in user) |
| Followers | `opencli twitter followers USERNAME` | `--limit N` (default 50) |
| Following | `opencli twitter following USERNAME` | `--limit N` (default 50) |
| Notifications | `opencli twitter notifications` | `--limit N` (default 20) |

---

## Step 3: Execute the Command

### General pattern

```bash
# Use -f json or -f yaml for structured output
opencli twitter timeline -f json --limit 20
opencli twitter timeline --type following --limit 20

# Recent tweets from a specific user
opencli twitter tweets elonmusk --limit 20 -f json

# Searching for financial topics
opencli twitter search "$AAPL earnings" --filter live --limit 10 -f json
opencli twitter search "Fed rate decision" --limit 20 -f yaml

# Trending topics
opencli twitter trending --limit 20 -f json
```

### Key rules

1. **Check setup first** — run `opencli doctor` before any other command if unsure about connectivity
2. **Use `-f json` or `-f yaml`** for structured output when processing data programmatically
3. **Use `-f csv`** when the user wants spreadsheet-compatible output
4. **Use `--limit N`** to control result count — start with 10-20 unless the user asks for more
5. **For search, use `--filter`** — `top` (default) for relevance, `live` for latest tweets
6. **Read-only** — don't post, like, retweet, reply, quote, follow, or delete, even though opencli exposes some of these commands

### Output format flag (`-f`)

| Format | Flag | Best for |
|---|---|---|
| Table | `-f table` (default) | Human-readable terminal output |
| JSON | `-f json` | Programmatic processing, LLM context |
| YAML | `-f yaml` | Structured output, readable |
| Markdown | `-f md` | Documentation, reports |
| CSV | `-f csv` | Spreadsheet export |

### Output columns

Tweet-listing commands (`timeline`, `search`, `thread`) include: `id`, `author`, `text`, `created_at`, `likes`, `retweets`, `replies`, `views`, `url`, `has_media`, `media_urls`.

`tweets` (per-user posts) also includes `is_retweet`.

`bookmarks` columns: `author`, `text`, `likes`, `retweets`, `bookmarks`, `url`.

`trending` columns: `rank`, `topic`, `tweets`, `category`.

Profile (`profile`) columns: `screen_name`, `name`, `bio`, `location`, `url`, `followers`, `following`, `tweets`, `likes`, `verified`, `created_at`.

`followers` / `following` columns: `screen_name`, `name`, `bio`, `followers`.

`notifications` columns: `id`, `action`, `author`, `text`, `url`.

---

## Step 4: Present the Results

Lead with what matters for the user's research question rather than a raw dump. Attribute each tweet (@handle, text, engagement such as likes and views, and the URL when the user may want the full thread), group search results by theme, and note the bullish or bearish lean and where views are consensus or contrarian. For profiles, give follower count, bio, and notable recent activity. Keep browser session details private.

---

## Step 5: Diagnostics

If something isn't working, run:

```bash
opencli doctor
```

This checks daemon status, extension connectivity, and browser session health.

---

## Error Reference

| Error | Cause | Fix |
|-------|-------|-----|
| `Extension not connected` | Browser Bridge not installed/enabled | Install extension and enable it in Chrome |
| `No session` | Not logged into x.com | Login to x.com in Chrome |
| `CSRF token missing` | Cookie expired or page needs refresh | Refresh x.com in Chrome |
| Rate limited | Too many requests | Wait a few minutes, then retry |

---

## Reference Files

- `references/commands.md` — Complete read command reference with all flags, research workflows, and usage examples
- `references/schema.md` — Output format documentation and column definitions

Read the reference files when you need exact command syntax, research workflow patterns, or output details.