headless-twitter 1.1.0

package/EXAMPLES.md

@@ -0,0 +1,47 @@
+# Examples
+
+## First time setup
+
+```bash
+npm install -g headless-twitter
+npx playwright install chromium
+headless-twitter twitter timeline '' 0 --setup
+# Log in to Twitter in the browser window that opens
+# Close when done — session saved, no re-auth needed
+```
+
+## Read timeline
+
+```bash
+headless-twitter twitter timeline '' 20
+```
+
+## Search tweets
+
+```bash
+headless-twitter twitter search "golang concurrency" 15
+```
+
+## Get user's tweets
+
+```bash
+headless-twitter twitter user "@gvanrossum" 10
+```
+
+## JSON output (for piping)
+
+```bash
+headless-twitter twitter timeline '' 10 --json | jq '.tweets[0]'
+```
+
+## Save to file
+
+```bash
+headless-twitter twitter timeline '' 50 --json > tweets.json
+```
+
+## Use custom session
+
+```bash
+HT_SESSION_DIR=~/.twitter-work headless-twitter twitter timeline '' 10
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 om-ashish-soni
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,195 @@
+# headless-twitter
+
+**Headless Twitter/X reader. Zero mutations. Raw output.**
+
+Uses Playwright to intercept Twitter's GraphQL XHR responses directly. Strictly read-only. Two modes:
+
+- **`--use-chrome`** (recommended): Connects to your logged-in Chrome via CDP. Zero login friction. Auto-launches Chrome if needed.
+- **`--setup`**: One-time Playwright session login. Headless after setup.
+
+## Install
+
+### Via npm (recommended)
+
+```bash
+npm install -g headless-twitter
+npx playwright install chromium
+```
+
+Then:
+
+```bash
+headless-twitter twitter timeline '' 20 --use-chrome
+```
+
+### From source
+
+```bash
+git clone https://github.com/om-ashish-soni/headless-twitter.git
+cd headless-twitter
+npm install
+npx playwright install chromium
+node index.js twitter timeline '' 20 --use-chrome
+```
+
+## Quick Start (Chrome CDP — recommended)
+
+```bash
+node index.js twitter timeline '' 20 --use-chrome
+```
+
+That's it. On first run:
+1. Copies your Chrome profile to `~/.config/google-chrome-debug/`
+2. Launches Chrome with CDP debug port (9222)
+3. Connects, opens a tab, reads tweets, closes the tab
+4. Chrome stays running — subsequent runs connect instantly
+
+No manual login. No setup step. Uses your existing Twitter session from Chrome.
+
+### Custom CDP port
+
+```bash
+node index.js twitter timeline '' 20 --use-chrome --cdp-url http://localhost:9333
+```
+
+## Alternative: Playwright Session Setup
+
+If you prefer not to use your Chrome profile:
+
+```bash
+node index.js twitter timeline '' 0 --setup
+```
+
+Opens a visible Chrome window. Log into Twitter manually. Session saved to `~/.headless-twitter/sessions/twitter/`. All future runs are headless.
+
+## Usage
+
+```bash
+# Home timeline (top 20 tweets)
+node index.js twitter timeline '' 20 --use-chrome
+
+# Following feed
+node index.js twitter following '' 10 --use-chrome
+
+# Search
+node index.js twitter search "rust cli tools" 15 --use-chrome
+
+# User tweets
+node index.js twitter user "@karpathy" 10 --use-chrome
+
+# JSON output (for piping)
+node index.js twitter timeline '' 20 --use-chrome --json
+
+# Debug mode (show XHR endpoints + extraction details)
+node index.js twitter timeline '' 20 --use-chrome --debug
+```
+
+## Architecture
+
+```
+4-layer read-only enforcement:
+
+Layer 1 — Network:    block all non-GET requests
+Layer 2 — DOM:        freeze click/submit/input events via JS injection
+Layer 3 — Code:       no page.click(), page.fill(), page.submit() calls
+Layer 4 — Session:    persistent browser state (cookies, localStorage)
+```
+
+## What it does
+
+- Reads your Twitter timeline, Following feed, search results, or any user's tweets
+- Uses Playwright persistent sessions (login once, reuse forever)
+- Intercepts Twitter's GraphQL XHR responses directly (no DOM scraping)
+- Strictly read-only: all POST/PUT/DELETE/PATCH requests blocked at network level
+
+## What it NEVER does
+
+- Click any button, link, or interactive element
+- Submit any form
+- Like, retweet, follow, or bookmark
+- Send any POST/PUT/DELETE/PATCH request
+- Type into any input field
+- Modify any state on Twitter
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--use-chrome` | Connect to Chrome via CDP (auto-launches if needed) |
+| `--cdp-url URL` | CDP endpoint (default: `http://localhost:9222`) |
+| `--setup` | Interactive login for Playwright session |
+| `--json` | Output as JSON instead of TUI table |
+| `--debug` | Show XHR endpoints and extraction details |
+| `--help` | Show help message |
+
+## Environment Variables
+
+| Var | Default | Description |
+|-----|---------|-------------|
+| `HT_SESSION_DIR` | `~/.headless-twitter/sessions/twitter/` | Browser session path (Playwright mode only) |
+
+## Output
+
+### TUI (default)
+
+```
+====================================================================================================
+  Twitter Feed
+====================================================================================================
+
+[1] @author
+
+  Tweet text wrapped at 110 chars per line
+  continued...
+
+  📍 https://x.com/i/web/status/...
+  ❤️  2,580 | 🔄 320 | 💬 85
+  📅 Fri Apr 10 17:49:10 +0000 2026
+----------------------------------------------------------------------------------------------------
+```
+
+### JSON (`--json`)
+
+```json
+{
+  "source": "twitter",
+  "mode": "timeline",
+  "count": 10,
+  "tweets": [
+    {
+      "id": "...",
+      "text": "...",
+      "author": "@karpathy",
+      "likes": 2580,
+      "retweets": 320,
+      "replies": 85,
+      "time": "...",
+      "url": "..."
+    }
+  ]
+}
+```
+
+## Claude Code Integration
+
+Use as Claude Code skill. Claude can directly call:
+
+```javascript
+search_tweets(query="golang", limit=15)
+fetch_tweets_timeline(limit=20)
+fetch_user_tweets(username="@gvanrossum", limit=10)
+fetch_following(limit=20)
+```
+
+Example: "Fetch latest tweets about Rust and summarize discussions"
+
+Claude automatically invokes the functions and analyzes results.
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Playwright + Chromium
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,525 @@
+#!/usr/bin/env node
+
+// ─────────────────────────────────────────────────────────────────────────────
+// headless-twitter — Headless Twitter/X reader. Zero mutations. Raw output.
+// https://github.com/om-ashish-soni/headless-twitter
+// ─────────────────────────────────────────────────────────────────────────────
+
+const { chromium } = require('playwright');
+const path = require('path');
+const os = require('os');
+const fs = require('fs');
+const { execSync, spawn } = require('child_process');
+
+// ─── Help Message ───────────────────────────────────────────────────────────
+
+function showHelp() {
+  console.log(`
+headless-twitter — Headless Twitter/X reader. Zero mutations. Raw output.
+
+USAGE:
+  node index.js [SOURCE] [MODE] [QUERY] [LIMIT] [OPTIONS]
+
+ARGUMENTS:
+  SOURCE    twitter (default)
+  MODE      timeline | following | search | user (default: timeline)
+  QUERY     search term or username (required for search/user modes)
+  LIMIT     number of tweets (default: 20, max: 100)
+
+OPTIONS:
+  --setup       login to Twitter (interactive, one-time only)
+  --use-chrome  connect to running Chrome via CDP (no login needed)
+  --cdp-url URL CDP endpoint (default: http://localhost:9222)
+  --json        output as JSON instead of formatted table
+  --debug       show XHR responses and extraction details (troubleshooting)
+  --help        show this message
+
+EXAMPLES:
+  node index.js twitter timeline '' 20
+  node index.js twitter search "rust cli" 15
+  node index.js twitter user "@gvanrossum" 10
+  node index.js twitter following '' 20 --json
+  node index.js twitter timeline '' 0 --setup
+
+SETUP (one-time):
+  node index.js twitter timeline '' 0 --setup
+
+  What happens:
+  1. Visible Chrome window opens
+  2. Twitter login page shown (may redirect)
+  3. You log in with credentials + 2FA
+  4. Once logged in → tweets appear
+  5. Browser closes automatically
+  6. Session saved to ~/.headless-twitter/sessions/twitter/
+
+SESSION:
+  Reused for all future runs (Chrome runs in background, no browser window).
+  Set HT_SESSION_DIR to use alternate session.
+
+CHROME CDP (--use-chrome):
+  Skip login entirely — connect to your already-logged-in Chrome.
+
+  1. Close Chrome if running
+  2. Relaunch with: google-chrome --remote-debugging-port=9222
+     (or: chrome --remote-debugging-port=9222 on Mac)
+  3. Run: node index.js twitter timeline '' 20 --use-chrome
+
+  No session dir needed. No setup. Uses your existing cookies.
+
+READ-ONLY:
+  • No mutations allowed (blocks POST/PUT/DELETE/PATCH)
+  • Can't interact with page (no clicks, no typing, no forms)
+  • Reads Twitter's GraphQL responses directly
+`);
+}
+
+// ─── CLI Args ───────────────────────────────────────────────────────────────
+
+if (process.argv.includes('--help') || process.argv.includes('-h')) {
+  showHelp();
+  process.exit(0);
+}
+
+const SOURCE = process.argv[2] || 'twitter';
+const MODE   = process.argv[3] || 'timeline'; // timeline | following | search | user
+const QUERY  = process.argv[4] || '';
+const LIMIT  = parseInt(process.argv[5] || '20');
+const SETUP  = process.argv.includes('--setup');
+const USE_CHROME = process.argv.includes('--use-chrome');
+const CDP_URL = (() => {
+  const idx = process.argv.indexOf('--cdp-url');
+  return idx !== -1 && process.argv[idx + 1] ? process.argv[idx + 1] : 'http://localhost:9222';
+})();
+const JSON_OUT = process.argv.includes('--json');
+const DEBUG  = process.argv.includes('--debug');
+
+// ─── Input Validation ────────────────────────────────────────────────────────
+
+const VALID_MODES = ['timeline', 'following', 'search', 'user'];
+if (!VALID_MODES.includes(MODE)) {
+  console.error(`Error: Invalid mode '${MODE}'`);
+  console.error(`Valid modes: ${VALID_MODES.join(', ')}`);
+  process.exit(1);
+}
+
+if (isNaN(LIMIT) || LIMIT < 0) {
+  console.error(`Error: LIMIT must be a non-negative number, got '${process.argv[5]}'`);
+  process.exit(1);
+}
+
+if (LIMIT === 0 && !SETUP) {
+  console.error(`Error: LIMIT 0 only allowed with --setup flag`);
+  process.exit(1);
+}
+
+if (LIMIT > 100) {
+  console.error(`Error: LIMIT max is 100, got ${LIMIT}`);
+  process.exit(1);
+}
+
+if ((MODE === 'search' || MODE === 'user') && !QUERY) {
+  console.error(`Error: MODE '${MODE}' requires QUERY argument`);
+  console.error(`Usage: node index.js twitter ${MODE} "<query>" [LIMIT]`);
+  process.exit(1);
+}
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+const SESSION_DIR = process.env.HT_SESSION_DIR
+  || path.join(os.homedir(), '.headless-twitter', 'sessions', SOURCE);
+
+// ─── Read-Only Guards ───────────────────────────────────────────────────────
+
+async function installReadOnlyGuards(page) {
+  // Block all non-GET requests
+  await page.route('**/*', (route, request) => {
+    const method = request.method().toUpperCase();
+    if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
+      route.abort('blockedbyclient');
+      return;
+    }
+    route.continue();
+  });
+
+  // Freeze interactive elements
+  await page.addInitScript(() => {
+    const BLOCKED = ['click', 'submit', 'input', 'change', 'keydown', 'keypress', 'keyup'];
+    const orig = EventTarget.prototype.addEventListener;
+    EventTarget.prototype.addEventListener = function(type, listener, opts) {
+      if (BLOCKED.includes(type)) {
+        return orig.call(this, type, () => {}, opts);
+      }
+      return orig.call(this, type, listener, opts);
+    };
+    HTMLFormElement.prototype.submit = () => {};
+    HTMLFormElement.prototype.requestSubmit = () => {};
+  });
+}
+
+// ─── XHR Interception ───────────────────────────────────────────────────────
+
+async function interceptXHR(page) {
+  const captured = [];
+  const urls = new Set();
+
+  page.on('response', async (response) => {
+    const contentType = response.headers()['content-type'] || '';
+    if (!contentType.includes('application/json')) return;
+
+    const url = response.url();
+    if (!urls.has(url)) {
+      urls.add(url);
+      if (DEBUG) {
+        console.error(`[DEBUG] XHR: ${url.substring(0, 100)}`);
+      }
+    }
+
+    try {
+      const json = await response.json();
+      captured.push(json);
+    } catch (_) {}
+  });
+
+  if (DEBUG) {
+    setTimeout(() => {
+      console.error(`[DEBUG] Total XHR endpoints: ${urls.size}`);
+      console.error(`[DEBUG] Captured responses: ${captured.length}`);
+    }, 2000);
+  }
+
+  return captured;
+}
+
+// ─── Tweet Extraction ───────────────────────────────────────────────────────
+
+function extractTweetsFromGraphQL(data) {
+  const tweets = [];
+  const seen = new Set();
+  let tweetNodeCount = 0;
+  let tweetWithVisCount = 0;
+
+  const walk = (obj, depth = 0) => {
+    if (!obj || typeof obj !== 'object' || depth > 20) return;
+
+    // Handle TweetWithVisibilityResults wrapper
+    if (obj.__typename === 'TweetWithVisibilityResults' && obj.tweet) {
+      tweetWithVisCount++;
+      const merged = { ...obj.tweet, core: obj.core || obj.tweet.core };
+      walk(merged, depth + 1);
+      return;
+    }
+
+    if (obj.__typename === 'Tweet' && obj.legacy) {
+      tweetNodeCount++;
+      const t = obj.legacy;
+      if (seen.has(t.id_str)) return;
+      seen.add(t.id_str);
+
+      let author = 'unknown';
+      const userResult = obj.core?.user_results?.result;
+      const screenName = userResult?.legacy?.screen_name
+        || userResult?.core?.screen_name;
+      if (screenName) {
+        author = screenName;
+      }
+
+      tweets.push({
+        id:       t.id_str,
+        text:     t.full_text,
+        author:   author,
+        likes:    t.favorite_count || 0,
+        retweets: t.retweet_count || 0,
+        replies:  t.reply_count || 0,
+        time:     t.created_at,
+        url:      `https://x.com/i/web/status/${t.id_str}`,
+      });
+    }
+
+    Object.values(obj).forEach(v => walk(v, depth + 1));
+  };
+  walk(data);
+
+  if (DEBUG) {
+    console.error(`[DEBUG] Extract: found ${tweetWithVisCount} TweetWithVisibilityResults, ${tweetNodeCount} Tweet nodes, ${tweets.length} complete tweets`);
+  }
+
+  return tweets;
+}
+
+// ─── Scroll ─────────────────────────────────────────────────────────────────
+
+async function autoScroll(page, { maxScrolls = 5, delayMs = 1500 } = {}) {
+  for (let i = 0; i < maxScrolls; i++) {
+    await page.evaluate(() => window.scrollBy(0, window.innerHeight * 2));
+    await page.waitForTimeout(delayMs);
+  }
+}
+
+// ─── Output Formatters ──────────────────────────────────────────────────────
+
+function formatTweetsForTUI(tweets, limit = 20, mode = 'timeline', query = '') {
+  const lines = [];
+  lines.push('\n' + '═'.repeat(120));
+
+  // Header with context
+  let title = '📊 Twitter Feed';
+  if (mode === 'search') title = `🔍 Search: "${query}"`;
+  if (mode === 'user') title = `👤 User: ${query}`;
+  if (mode === 'following') title = '👥 Following';
+
+  lines.push(`  ${title}`);
+  lines.push('═'.repeat(120) + '\n');
+
+  const displayed = tweets.slice(0, limit);
+
+  if (displayed.length === 0) {
+    lines.push('  (no tweets found)');
+    lines.push('\n  Tips:');
+    if (mode === 'search') {
+      lines.push('    • Try a different search term');
+      lines.push('    • Check spelling and filters');
+    } else if (mode === 'user') {
+      lines.push('    • User may not exist or have no tweets');
+      lines.push('    • Try @username format');
+    } else if (mode === 'timeline') {
+      lines.push('    • Session may be expired, try: npm run setup');
+      lines.push('    • Or wait a moment and retry');
+    }
+    lines.push('');
+  } else {
+    displayed.forEach((tweet, idx) => {
+      lines.push(`[${idx + 1}] @${tweet.author}`);
+      lines.push('');
+
+      const wrapped = tweet.text.split('\n').flatMap(line => {
+        const matches = line.match(/.{1,110}/g);
+        return matches || [line];
+      });
+      wrapped.forEach(line => {
+        lines.push(`  ${line}`);
+      });
+      lines.push('');
+
+      lines.push(`  📍 ${tweet.url}`);
+      lines.push(`  ❤️  ${tweet.likes.toLocaleString()} | 🔄 ${tweet.retweets.toLocaleString()} | 💬 ${tweet.replies.toLocaleString()}`);
+      lines.push(`  📅 ${tweet.time}`);
+      lines.push('─'.repeat(120));
+    });
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Chrome CDP Auto-Launch ─────────────────────────────────────────────────
+
+const CHROME_DEBUG_DIR = path.join(os.homedir(), '.config', 'google-chrome-debug');
+const CHROME_DEFAULT_DIR = path.join(os.homedir(), '.config', 'google-chrome');
+
+function findChromeBinary() {
+  const candidates = ['google-chrome', 'google-chrome-stable', 'chromium-browser', 'chromium'];
+  for (const bin of candidates) {
+    try {
+      execSync(`which ${bin}`, { stdio: 'ignore' });
+      return bin;
+    } catch (_) {}
+  }
+  return null;
+}
+
+function isCdpReachable(url) {
+  try {
+    execSync(`curl -s --max-time 2 ${url}/json/version`, { stdio: 'ignore' });
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function ensureDebugProfile() {
+  if (fs.existsSync(path.join(CHROME_DEBUG_DIR, 'Default'))) return true;
+
+  if (!fs.existsSync(path.join(CHROME_DEFAULT_DIR, 'Default'))) {
+    console.error('Error: No Chrome profile found to copy');
+    console.error(`Expected: ${CHROME_DEFAULT_DIR}/Default`);
+    return false;
+  }
+
+  console.error('First run: copying Chrome profile for CDP mode...');
+  fs.mkdirSync(CHROME_DEBUG_DIR, { recursive: true });
+  execSync(`cp -r "${CHROME_DEFAULT_DIR}/Default" "${CHROME_DEBUG_DIR}/Default"`);
+  try { execSync(`cp "${CHROME_DEFAULT_DIR}/Local State" "${CHROME_DEBUG_DIR}/Local State"`); } catch (_) {}
+  console.error('Profile copied.');
+  return true;
+}
+
+async function autoLaunchChrome(cdpUrl) {
+  if (isCdpReachable(cdpUrl)) {
+    if (DEBUG) console.error('[DEBUG] CDP already reachable');
+    return;
+  }
+
+  const port = new URL(cdpUrl).port || '9222';
+  const bin = findChromeBinary();
+  if (!bin) {
+    console.error('Error: Chrome/Chromium not found in PATH');
+    process.exit(1);
+  }
+
+  if (!ensureDebugProfile()) process.exit(1);
+
+  // Kill existing Chrome (can't share debug port with existing instance)
+  try { execSync('killall -9 chrome google-chrome chromium 2>/dev/null'); } catch (_) {}
+  // Remove stale lock
+  try { fs.unlinkSync(path.join(CHROME_DEBUG_DIR, 'SingletonLock')); } catch (_) {}
+
+  console.error(`Launching Chrome with CDP on port ${port}...`);
+  const child = spawn(bin, [
+    `--remote-debugging-port=${port}`,
+    '--remote-allow-origins=*',
+    `--user-data-dir=${CHROME_DEBUG_DIR}`,
+    '--no-first-run',
+    '--restore-last-session',
+  ], { stdio: 'ignore', detached: true });
+  child.unref();
+
+  // Wait for CDP to come up (max 15s)
+  for (let i = 0; i < 30; i++) {
+    await new Promise(r => setTimeout(r, 500));
+    if (isCdpReachable(cdpUrl)) {
+      if (DEBUG) console.error('[DEBUG] Chrome CDP ready');
+      return;
+    }
+  }
+
+  console.error('Error: Chrome launched but CDP not responding after 15s');
+  process.exit(1);
+}
+
+// ─── Main ──────────────────────────────────────────────────────────────────
+
+async function run() {
+  try {
+    let browser = null;  // only set for CDP mode
+    let context;
+    let page;
+
+    if (USE_CHROME) {
+      // ─── CDP: auto-launch + connect to Chrome ───
+      await autoLaunchChrome(CDP_URL);
+      if (DEBUG) console.error(`[DEBUG] Connecting to Chrome via CDP: ${CDP_URL}`);
+      browser = await chromium.connectOverCDP(CDP_URL);
+      context = browser.contexts()[0];
+      if (!context) {
+        console.error('Error: No browser context found in Chrome');
+        process.exit(1);
+      }
+      page = await context.newPage();
+      if (DEBUG) console.error(`[DEBUG] Connected to Chrome, opened new tab`);
+
+    } else {
+      // ─── Default: Playwright persistent context ───
+      const defaultProfile = path.join(SESSION_DIR, 'Default');
+      if (!SETUP && !fs.existsSync(defaultProfile)) {
+        console.error(`Error: Twitter session not found`);
+        console.error('');
+        console.error('Options:');
+        console.error('  1. First time setup:  npm run setup');
+        console.error('  2. Use existing Chrome: node index.js twitter timeline \'\' 20 --use-chrome');
+        process.exit(1);
+      }
+
+      context = await chromium.launchPersistentContext(SESSION_DIR, {
+        headless: false,
+        args: [
+          '--no-sandbox',
+          '--disable-blink-features=AutomationControlled',
+          '--disable-extensions',
+        ],
+        userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+      });
+      page = await context.newPage();
+    }
+
+    await installReadOnlyGuards(page);
+    const captured = await interceptXHR(page);
+
+    const urls = {
+      timeline: 'https://twitter.com/home',
+      search:   `https://twitter.com/search?q=${encodeURIComponent(QUERY)}&f=live`,
+      user:     `https://twitter.com/${QUERY}`,
+      following: 'https://twitter.com/following',
+    };
+
+    const gotoUrl = urls[MODE] || urls.timeline;
+    if (DEBUG) console.error(`[DEBUG] Navigating to: ${gotoUrl}`);
+
+    await page.goto(gotoUrl, { waitUntil: 'networkidle', timeout: 30000 });
+    if (DEBUG) console.error(`[DEBUG] Page loaded`);
+
+    // Setup: wait for user login (not applicable in CDP mode)
+    if (SETUP && !USE_CHROME) {
+      if (DEBUG) console.error(`[DEBUG] Waiting for login... (keep browser window open)`);
+      try {
+        await page.waitForURL('**/home', { timeout: 5 * 60 * 1000 });
+        if (DEBUG) console.error(`[DEBUG] Login detected!`);
+      } catch (e) {
+        console.error(`[DEBUG] Setup timeout - no login detected after 5 minutes`);
+        throw e;
+      }
+    }
+
+    await autoScroll(page, { maxScrolls: 3, delayMs: 1500 });
+    if (DEBUG) console.error(`[DEBUG] Scrolling complete`);
+
+    await page.waitForTimeout(2000);
+    if (DEBUG) console.error(`[DEBUG] Wait complete, before extraction`);
+
+    if (DEBUG) {
+      const pageTitle = await page.title();
+      const tweetElements = await page.evaluate(() => {
+        return document.querySelectorAll('[data-testid="tweet"]').length;
+      });
+      console.error(`[DEBUG] Page title: ${pageTitle}`);
+      console.error(`[DEBUG] Tweet elements in DOM: ${tweetElements}`);
+    }
+
+    const tweets = [];
+    for (const data of captured) {
+      tweets.push(...extractTweetsFromGraphQL(data));
+      if (tweets.length >= LIMIT) break;
+    }
+
+    // Output
+    const result = tweets.slice(0, LIMIT);
+    if (JSON_OUT) {
+      process.stdout.write(JSON.stringify({
+        source: SOURCE,
+        mode: MODE,
+        query: QUERY,
+        count: result.length,
+        tweets: result,
+      }));
+    } else {
+      process.stdout.write(formatTweetsForTUI(result, LIMIT, MODE, QUERY));
+    }
+
+    // Cleanup: CDP mode closes only the tab, default mode closes context
+    if (USE_CHROME) {
+      await page.close();
+      browser.close();
+    } else {
+      await context.close();
+    }
+
+    if (SETUP && !USE_CHROME) {
+      console.error('\n✅ Setup complete! Session saved.');
+      console.error('Now run: node index.js twitter timeline \'\' 20');
+      console.error('Browser closed. It will run in background on future commands.');
+    }
+  } catch (e) {
+    process.stderr.write(`Error: ${e.message}\n`);
+    process.exit(1);
+  }
+}
+
+run();

package/mcp-server.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+/**
+ * headless-twitter MCP Server
+ * Exposes tweet fetching functions to Claude
+ */
+
+const { chromium } = require('playwright');
+const path = require('path');
+const os = require('os');
+
+const SESSION_DIR = process.env.HT_SESSION_DIR
+  || path.join(os.homedir(), '.headless-twitter', 'sessions', 'twitter');
+
+// ─── Core Functions ─────────────────────────────────────────────────────────
+
+async function installReadOnlyGuards(page) {
+  await page.route('**/*', (route, request) => {
+    const method = request.method().toUpperCase();
+    if (['POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
+      route.abort('blockedbyclient');
+      return;
+    }
+    route.continue();
+  });
+
+  await page.addInitScript(() => {
+    const BLOCKED = ['click', 'submit', 'input', 'change', 'keydown', 'keypress', 'keyup'];
+    const orig = EventTarget.prototype.addEventListener;
+    EventTarget.prototype.addEventListener = function(type, listener, opts) {
+      if (BLOCKED.includes(type)) return orig.call(this, type, () => {}, opts);
+      return orig.call(this, type, listener, opts);
+    };
+    HTMLFormElement.prototype.submit = () => {};
+    HTMLFormElement.prototype.requestSubmit = () => {};
+  });
+}
+
+async function interceptXHR(page) {
+  const captured = [];
+  page.on('response', async (response) => {
+    const contentType = response.headers()['content-type'] || '';
+    if (!contentType.includes('application/json')) return;
+    try {
+      const json = await response.json();
+      captured.push(json);
+    } catch (_) {}
+  });
+  return captured;
+}
+
+function extractTweetsFromGraphQL(data) {
+  const tweets = [];
+  const seen = new Set();
+
+  const walk = (obj, depth = 0) => {
+    if (!obj || typeof obj !== 'object' || depth > 20) return;
+
+    if (obj.__typename === 'TweetWithVisibilityResults' && obj.tweet) {
+      const merged = { ...obj.tweet, core: obj.core || obj.tweet.core };
+      walk(merged, depth + 1);
+      return;
+    }
+
+    if (obj.__typename === 'Tweet' && obj.legacy) {
+      const t = obj.legacy;
+      if (seen.has(t.id_str)) return;
+      seen.add(t.id_str);
+
+      let author = 'unknown';
+      const userLegacy = obj.core?.user_results?.result?.legacy;
+      if (userLegacy && userLegacy.screen_name) {
+        author = userLegacy.screen_name;
+      }
+
+      tweets.push({
+        id:       t.id_str,
+        text:     t.full_text,
+        author:   author,
+        likes:    t.favorite_count || 0,
+        retweets: t.retweet_count || 0,
+        replies:  t.reply_count || 0,
+        time:     t.created_at,
+        url:      `https://x.com/i/web/status/${t.id_str}`,
+      });
+    }
+
+    Object.values(obj).forEach(v => walk(v, depth + 1));
+  };
+  walk(data);
+  return tweets;
+}
+
+async function autoScroll(page, { maxScrolls = 3, delayMs = 1500 } = {}) {
+  for (let i = 0; i < maxScrolls; i++) {
+    await page.evaluate(() => window.scrollBy(0, window.innerHeight * 2));
+    await page.waitForTimeout(delayMs);
+  }
+}
+
+async function fetchTweets(mode, query, limit) {
+  try {
+    const context = await chromium.launchPersistentContext(SESSION_DIR, {
+      headless: true,
+      args: [
+        '--no-sandbox',
+        '--disable-blink-features=AutomationControlled',
+        '--disable-extensions',
+      ],
+      userAgent: 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36',
+    });
+
+    const page = await context.newPage();
+    await installReadOnlyGuards(page);
+    const captured = await interceptXHR(page);
+
+    const urls = {
+      timeline: 'https://twitter.com/home',
+      search:   `https://twitter.com/search?q=${encodeURIComponent(query)}&f=live`,
+      user:     `https://twitter.com/${query}`,
+      following: 'https://twitter.com/following',
+    };
+
+    await page.goto(urls[mode] || urls.timeline, { waitUntil: 'networkidle', timeout: 30000 });
+    await autoScroll(page);
+    await page.waitForTimeout(2000);
+
+    const tweets = [];
+    for (const data of captured) {
+      tweets.push(...extractTweetsFromGraphQL(data));
+      if (tweets.length >= limit) break;
+    }
+
+    await context.close();
+    return tweets.slice(0, limit);
+  } catch (error) {
+    throw new Error(`Failed to fetch tweets: ${error.message}`);
+  }
+}
+
+// ─── MCP Tools ──────────────────────────────────────────────────────────────
+
+const tools = [
+  {
+    name: 'fetch_tweets_timeline',
+    description: 'Fetch tweets from your home timeline',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'Number of tweets to fetch (default: 20, max: 100)',
+          default: 20,
+        },
+      },
+    },
+  },
+  {
+    name: 'search_tweets',
+    description: 'Search for tweets by query',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query (e.g., "golang", "ai agents")',
+        },
+        limit: {
+          type: 'number',
+          description: 'Number of tweets to fetch (default: 15, max: 100)',
+          default: 15,
+        },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'fetch_user_tweets',
+    description: 'Fetch tweets from a specific user',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        username: {
+          type: 'string',
+          description: 'Twitter username (with or without @)',
+        },
+        limit: {
+          type: 'number',
+          description: 'Number of tweets to fetch (default: 10, max: 100)',
+          default: 10,
+        },
+      },
+      required: ['username'],
+    },
+  },
+  {
+    name: 'fetch_following',
+    description: 'Fetch tweets from accounts you follow',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        limit: {
+          type: 'number',
+          description: 'Number of tweets to fetch (default: 20, max: 100)',
+          default: 20,
+        },
+      },
+    },
+  },
+];
+
+// ─── Tool Handlers ──────────────────────────────────────────────────────────
+
+async function handleToolCall(name, input) {
+  const limit = Math.min(input.limit || 20, 100);
+
+  switch (name) {
+    case 'fetch_tweets_timeline':
+      return await fetchTweets('timeline', '', limit);
+
+    case 'search_tweets':
+      if (!input.query) throw new Error('query is required');
+      return await fetchTweets('search', input.query, limit);
+
+    case 'fetch_user_tweets':
+      if (!input.username) throw new Error('username is required');
+      const username = input.username.startsWith('@') ? input.username : `@${input.username}`;
+      return await fetchTweets('user', username, limit);
+
+    case 'fetch_following':
+      return await fetchTweets('following', '', limit);
+
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+// ─── Export for Claude Code ────────────────────────────────────────────────
+
+module.exports = {
+  tools,
+  handleToolCall,
+};

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "headless-twitter",
+  "version": "1.1.0",
+  "description": "Headless Twitter/X reader. Playwright XHR interception. Strictly read-only. Zero mutations.",
+  "main": "index.js",
+  "bin": {
+    "headless-twitter": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "mcp-server.js",
+    "README.md",
+    "EXAMPLES.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "setup": "node index.js twitter timeline '' 0 --setup",
+    "chrome": "node index.js twitter timeline '' 20 --use-chrome"
+  },
+  "keywords": [
+    "twitter",
+    "x",
+    "headless",
+    "playwright",
+    "read-only",
+    "scraper",
+    "feed-reader",
+    "xhr"
+  ],
+  "author": "om-ashish-soni",
+  "license": "MIT",
+  "dependencies": {
+    "playwright": "^1.49.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}