twitter-reader

# 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

# opencli Twitter Command Reference (Read-Only)

Complete read-only reference for Twitter commands in [opencli](https://github.com/jackwener/opencli), scoped to financial research use cases.

Install: `npm install -g @jackwener/opencli`

**This skill is read-only.** Write operations (post, like, retweet, reply, quote, follow, delete) are NOT supported in this finance skill.

---

## Setup

opencli authenticates via your existing Chrome browser session — no API keys or credentials needed.

**Requirements:**
1. Node.js >= 20 (or Bun >= 1.0)
2. Chrome with the Browser Bridge extension installed
3. Logged into x.com in Chrome

**Install the Browser Bridge extension:**
1. Download `opencli-extension-v{version}.zip` from the [GitHub Releases page](https://github.com/jackwener/opencli/releases)
2. Unzip it, open `chrome://extensions`, enable **Developer mode**
3. Click **Load unpacked** and select the unzipped folder

**Verify setup:**
```bash
opencli doctor
```

This auto-starts the daemon, verifies extension connectivity, and checks browser session health.

---

## Read Operations

### Timeline (Home Feed)

```bash
opencli twitter timeline                          # "For You" feed (default, limit 20)
opencli twitter timeline --type following         # "Following" tab (chronological)
opencli twitter timeline --type for-you           # "For You" tab (algorithmic, explicit)
opencli twitter timeline --limit 50               # Limit count
opencli twitter timeline -f json                  # JSON output
opencli twitter timeline -f yaml                  # YAML output
```

**Flags:** `--type` (`for-you` | `following`, default `for-you`), `--limit` (default 20).

### Search

```bash
opencli twitter search "keyword"                  # Basic search (top results, limit 15)
opencli twitter search "AI agent" --filter live --limit 50    # Latest tweets
opencli twitter search "topic" -f json            # JSON output
opencli twitter search "topic" -f csv             # CSV output

# Financial research examples
opencli twitter search "$AAPL earnings" --filter live --limit 20 -f json
opencli twitter search "Fed rate decision" --limit 20 -f yaml
opencli twitter search "market crash" --filter live --limit 15 -f json
```

**Flags:** `--filter` (`top` | `live`, default `top`), `--limit` (default 15).

### Trending Topics

```bash
opencli twitter trending                          # Top 20 trending topics (default)
opencli twitter trending --limit 10               # Limit count
opencli twitter trending -f json                  # JSON output
```

### Bookmarks

```bash
opencli twitter bookmarks                         # View bookmarked tweets
opencli twitter bookmarks --limit 30              # Limit count
opencli twitter bookmarks -f json                 # JSON output
```

### Thread / Tweet Detail

```bash
opencli twitter thread TWEET_ID                   # View tweet thread (default limit 50)
opencli twitter thread TWEET_ID --limit 20        # Limit replies
opencli twitter thread TWEET_ID -f json           # JSON output
```

### Twitter Articles

```bash
opencli twitter article TWEET_ID                  # View long-form article
opencli twitter article TWEET_ID -f json          # JSON output
```

### User Data

```bash
opencli twitter profile                           # Defaults to logged-in user
opencli twitter profile elonmusk                  # Look up a specific user
opencli twitter profile elonmusk -f json          # JSON output
opencli twitter followers elonmusk                # List followers (default limit 50)
opencli twitter followers elonmusk --limit 100    # Custom limit
opencli twitter following elonmusk                # List following (default limit 50)
```

### Recent Tweets from a User

Fetches a user's most recent posts (chronological, excludes pinned). Added in opencli 1.7.6.

```bash
opencli twitter tweets elonmusk                   # Most recent tweets (default limit 20)
opencli twitter tweets elonmusk --limit 50        # More tweets
opencli twitter tweets jimcramer -f json          # JSON output
```

**Columns:** `author`, `created_at`, `is_retweet`, `text`, `likes`, `retweets`, `replies`, `views`, `url`, `has_media`, `media_urls`.

### Notifications

```bash
opencli twitter notifications                     # View notifications
opencli twitter notifications -f json             # JSON output
```

---

## Output Formats

All commands support the `-f` / `--format` flag:

| Format | Flag | Description |
|---|---|---|
| Table | `-f table` (default) | Rich CLI table with bold headers, word wrapping, footer with count/elapsed time |
| JSON | `-f json` | Pretty-printed JSON (2-space indent) |
| YAML | `-f yaml` | Structured YAML |
| Markdown | `-f md` | Pipe-delimited markdown tables |
| CSV | `-f csv` | Comma-separated values with proper quoting/escaping |

### Output columns by command

| Command | Columns |
|---|---|
| `timeline`, `search`, `thread` | `id`, `author`, `text`, `likes`, `retweets`, `replies`, `views`, `created_at`, `url`, `has_media`, `media_urls` |
| `tweets` | `author`, `created_at`, `is_retweet`, `text`, `likes`, `retweets`, `replies`, `views`, `url`, `has_media`, `media_urls` |
| `bookmarks` | `author`, `text`, `likes`, `retweets`, `bookmarks`, `url` |
| `trending` | `rank`, `topic`, `tweets`, `category` |
| `profile` | `screen_name`, `name`, `bio`, `location`, `url`, `followers`, `following`, `tweets`, `likes`, `verified`, `created_at` |
| `followers`, `following` | `screen_name`, `name`, `bio`, `followers` |
| `notifications` | `id`, `action`, `author`, `text`, `url` |

**Note:** The `has_media` and `media_urls` columns were added in opencli 1.7.7.

---

## Financial Research Workflows

### Search for earnings sentiment

```bash
opencli twitter search "$AAPL earnings" --filter live --limit 20 -f json
opencli twitter search "$TSLA delivery numbers" --filter live --limit 15 -f json
```

### Monitor fintwit for a ticker

```bash
opencli twitter search "$NVDA" --filter live --limit 30 -f json
opencli twitter search "$SPY puts" --filter live --limit 20 -f json
```

### Track analyst commentary

```bash
# Check trending topics for market themes
opencli twitter trending --limit 20 -f json

# Search for specific analyst takes
opencli twitter search "price target AAPL" --filter live --limit 15 -f json

# Read recent tweets from a specific analyst or fintwit account
opencli twitter tweets jimcramer --limit 30 -f json
opencli twitter tweets elerianm --limit 20 -f json
```

### Macro / Fed watching

```bash
opencli twitter search "Fed rate decision" --filter live --limit 20 -f json
opencli twitter search "CPI report" --filter live --limit 15 -f json
opencli twitter search "inflation data" --filter live --limit 20 -f yaml
```

### Daily market reading workflow

```bash
# Check trending topics
opencli twitter trending --limit 10 -f json

# Read your feed
opencli twitter timeline --type following --limit 30 -f json

# Check bookmarks
opencli twitter bookmarks --limit 20 -f json

# Search for market outlook
opencli twitter search "market outlook" --filter live --limit 30 -f json
```

### Export for analysis

```bash
# CSV for spreadsheet analysis
opencli twitter search "AI stocks" --limit 50 -f csv > ai_stocks.csv

# JSON for programmatic processing
opencli twitter search "earnings beat" --limit 30 -f json > earnings.json
```

---

## Error Reference

| Error | Cause | Fix |
|-------|-------|-----|
| `Extension not connected` | Browser Bridge not installed | Install the Browser Bridge Chrome extension |
| `Daemon not running` | opencli daemon not started | Run `opencli doctor` to auto-start |
| `No session for twitter.com` | Not logged into x.com | Login to x.com in Chrome |
| `CSRF token missing` | Cookie expired | Refresh x.com in Chrome |
| Rate limited | Too many requests | Wait a few minutes, then retry |

---

## Limitations

- **Read-only in this skill** — write operations are not supported for finance use
- **No DMs** — direct messages are not exposed via read commands in this skill
- **Requires Chrome** — opencli uses Chrome's Browser Bridge; other browsers are not supported
- **Single browser profile** — uses the active Chrome profile's session

---

## Best Practices

- **Keep request volumes low** — use `--limit 20` instead of `--limit 500`
- **Use `opencli doctor`** before your first command in a session to verify connectivity
- **Use `-f json`** for programmatic processing and LLM context
- **Use `-f csv`** when the user wants to analyze data in a spreadsheet
- **Prefer `--filter live`** for time-sensitive financial searches (earnings, breaking news)

# Output Format Reference

opencli supports multiple output formats for all Twitter commands via the `-f` / `--format` flag.

## Formats

| Format | Flag | Description |
|---|---|---|
| Table | `-f table` | Default in a TTY. Rich CLI table with bold headers, word wrapping, and a footer showing row count and elapsed time |
| JSON | `-f json` | Pretty-printed JSON array with 2-space indent — preferred for agents |
| YAML | `-f yaml` | Default in non-TTY. Structured YAML with 120-char line width |
| Plain | `-f plain` | Prints a single primary field (for chat-style commands) |
| Markdown | `-f md` | Pipe-delimited markdown table |
| CSV | `-f csv` | Comma-separated values with proper quoting and escaping |

## Column Definitions

### Tweet list columns (`timeline`, `search`, `thread`)

| Column | Type | Description |
|---|---|---|
| `id` | string | Tweet ID |
| `author` | string | @handle of the tweet author |
| `text` | string | Tweet text content |
| `likes` | number | Like count |
| `retweets` | number | Retweet count |
| `replies` | number | Reply count |
| `views` | number | View count |
| `created_at` | string | Timestamp of the tweet |
| `url` | string | Direct URL to the tweet |
| `has_media` | boolean | Whether the tweet contains media (images/video) — added in 1.7.7 |
| `media_urls` | string[] | URLs of attached media — added in 1.7.7 |

### Per-user tweets columns (`tweets`)

Same as tweet-list columns above, plus:

| Column | Type | Description |
|---|---|---|
| `is_retweet` | boolean | Whether the post is a retweet of another author |

`tweets` command returns a user's most recent posts in chronological order, excluding the pinned tweet. Added in opencli 1.7.6.

### Bookmark columns (`bookmarks`)

| Column | Type | Description |
|---|---|---|
| `author` | string | @handle of the tweet author |
| `text` | string | Tweet text content |
| `likes` | number | Like count |
| `retweets` | number | Retweet count |
| `bookmarks` | number | Bookmark count |
| `url` | string | Direct URL to the tweet |

### Trending columns (`trending`)

| Column | Type | Description |
|---|---|---|
| `rank` | number | Trending rank position |
| `topic` | string | Trending topic or hashtag |
| `tweets` | number | Number of tweets about the topic |
| `category` | string | Category label from X (e.g., "Business", "Sports") |

### Profile columns (`profile`)

| Column | Type | Description |
|---|---|---|
| `screen_name` | string | @handle |
| `name` | string | Display name |
| `bio` | string | Profile bio/description |
| `location` | string | User-provided location |
| `url` | string | User's linked website |
| `followers` | number | Follower count |
| `following` | number | Following count |
| `tweets` | number | Total tweets |
| `likes` | number | Total likes |
| `verified` | boolean | Verification status |
| `created_at` | string | Account creation timestamp |

### User list columns (`followers`, `following`)

| Column | Type | Description |
|---|---|---|
| `screen_name` | string | @handle |
| `name` | string | Display name |
| `bio` | string | Profile bio/description |
| `followers` | number | Follower count |

### Notification columns (`notifications`)

| Column | Type | Description |
|---|---|---|
| `id` | string | Notification ID |
| `action` | string | Action type (like, retweet, follow, reply, mention, etc.) |
| `author` | string | @handle of the account that triggered the notification |
| `text` | string | Notification text / related tweet text |
| `url` | string | Direct URL to the notification's source |

## JSON Example

```json
[
  {
    "id": "1234567890",
    "author": "@exampleuser",
    "text": "Breaking: $AAPL earnings beat expectations...",
    "likes": 1523,
    "retweets": 240,
    "replies": 88,
    "views": 89000,
    "created_at": "2026-03-26T14:30:00Z",
    "url": "https://x.com/exampleuser/status/1234567890",
    "has_media": true,
    "media_urls": ["https://pbs.twimg.com/media/abc123.jpg"]
  }
]
```

## Notes

- Table format includes a footer with total row count and elapsed time
- JSON output is a flat array (no envelope wrapper)
- CSV properly escapes commas and quotes within fields
- Markdown format is suitable for pasting into documents or LLM context
- For programmatic use by agents, prefer `-f json`

---
name: twitter-reader
description: >
  Read Twitter/X for financial research using opencli (read-only).
  Use this skill whenever the user wants to read their Twitter feed, search for financial tweets,
  view bookmarks, look up user profiles, or gather market sentiment from Twitter/X.
  Triggers include: "check my feed", "search Twitter for", "show my bookmarks",
  "who follows", "look up @user", "what's trending about", "market sentiment on Twitter",
  "what are people saying about AAPL", "recent tweets from @elonmusk", "show me @user's posts",
  "fintwit", any mention of Twitter/X in context of reading financial news or market research.
  This skill is READ-ONLY — it does NOT support posting, liking, retweeting, or any write operations.
---

# Twitter Skill (Read-Only)

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. **NEVER execute write operations** — this skill is read-only; do not post, like, retweet, reply, quote, follow, or delete

### 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

After fetching data, present it clearly for financial research:

1. **Summarize key content** — highlight the most relevant tweets for the user's financial research
2. **Include attribution** — show @username, tweet text, and engagement metrics (likes, views)
3. **Provide tweet URLs** when the user might want to read the full thread
4. **For search results**, group by relevance and highlight key themes, sentiment, or market signals
5. **For user profiles**, present follower count, bio, and notable recent activity
6. **Flag sentiment** — note bullish/bearish sentiment, consensus vs contrarian views
7. **Treat sessions as private** — never expose browser session details

---

## 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.