x-browser 0.1.2__tar.gz

x_browser-0.1.2/.github/workflows/publish.yml

@@ -0,0 +1,24 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

x_browser-0.1.2/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+*.egg
+.eggs/
+dist/
+build/
+.venv/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# x-browser session data (contains login cookies!)
+chrome-data/
+
+# Environment / secrets
+.env
+.env.*

x_browser-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shivam Tiwari
+
+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.

x_browser-0.1.2/LLMs.md

@@ -0,0 +1,172 @@
+# x-browser — LLM Codebase Guide
+
+You are working on **x-browser**, a browser-based X/Twitter automation tool. It uses Playwright to control real Chrome via CDP, avoiding all API restrictions.
+
+---
+
+## Architecture
+
+```
+src/x_browser/
+├── __init__.py       # Package marker
+├── cli.py            # Click CLI — all commands, entry point
+├── browser.py        # Chrome launch + CDP connection
+├── config.py         # Politeness delays, config load/save
+├── actions.py        # Write operations (post, like, retweet, reply, quote, delete, bookmark)
+├── scrapers.py       # Read operations (get tweet, search, user profile, timeline, followers, mentions, bookmarks)
+└── formatters.py     # Output modes: human (Rich), JSON, TSV, markdown
+```
+
+```
+scripts/
+└── search-and-like.py   # Example long-running automation script
+```
+
+---
+
+## Module details
+
+### `browser.py` — Browser session management
+
+**Key insight:** Chrome is launched as a normal subprocess with `--remote-debugging-port`, then Playwright connects over CDP. This means zero automation flags — X cannot detect it.
+
+- `XBrowser` class: async context manager, holds Chrome process + Playwright connection
+- `XBrowser(headless=True/False)` — headless uses `--headless=new` flag
+- Session data persists in `~/.config/x-browser/chrome-data/`
+- `login_interactive()` — opens headed Chrome, waits for user to log in, saves session
+- `ensure_logged_in(page)` — checks if session is still valid
+
+### `config.py` — Configuration
+
+- `Config` dataclass with `min_politeness_delay` and `max_politeness_delay`
+- Defaults: 3s min, 30s max
+- Loads from `~/.config/x-browser/config.json`, falls back to defaults
+- `Config.save()` persists to disk
+- `config.politeness_wait()` — async sleep for random(min, max) seconds, logs to stderr
+
+### `actions.py` — Write operations
+
+Every function signature follows this pattern:
+```python
+async def action_name(
+    page: Page,
+    ...,                          # action-specific args
+    *,
+    config: Config | None = None, # uses Config.load() if None
+    min_delay: float | None = None,
+    max_delay: float | None = None,
+) -> dict:
+```
+
+Every function calls `politeness_wait()` as its first line, then performs browser interactions.
+
+Functions and what they do:
+- `tweet_post(page, text, poll_options=None)` — navigates to `/compose/post`, types, clicks Post
+- `tweet_delete(page, id_or_url)` — navigates to tweet, clicks ⋯ → Delete → Confirm
+- `tweet_reply(page, id_or_url, text)` — navigates to tweet, clicks reply, types, posts
+- `tweet_quote(page, id_or_url, text)` — navigates to tweet, clicks repost → Quote, types, posts
+- `like(page, id_or_url)` — navigates to tweet, clicks heart (`data-testid="like"`)
+- `retweet(page, id_or_url)` — navigates to tweet, clicks repost → Repost
+- `follow(page, username)` — navigates to user profile, clicks Follow button
+- `bookmark(page, id_or_url)` — navigates to tweet, clicks bookmark icon
+- `unbookmark(page, id_or_url)` — navigates to tweet, clicks removeBookmark icon
+
+All return `{"ok": True, ...}` dicts.
+
+### `scrapers.py` — Read operations
+
+Functions return Python dicts or lists of dicts. No politeness delay on reads.
+
+- `tweet_get(page, id_or_url)` → dict with: text, author_username, author_name, created_at, id, url, reply_count, retweet_count, like_count, view_count
+- `tweet_metrics(page, id_or_url)` → subset of tweet_get focused on counts
+- `tweet_search(page, query, max_results=10)` → list of tweet dicts
+- `user_get(page, username)` → dict with: username, name, description, followers_count, following_count, joined, location, url
+- `user_timeline(page, username, max_results=10)` → list of tweet dicts
+- `user_followers(page, username, max_results=100)` → list of user dicts
+- `user_following(page, username, max_results=100)` → list of user dicts
+- `me_mentions(page, max_results=10)` → list of tweet dicts
+- `me_bookmarks(page, max_results=10)` → list of tweet dicts
+
+Key helper: `_extract_tweet_from_article(article, page)` — extracts data from a single `<article data-testid="tweet">` element.
+
+### `formatters.py` — Output formatting
+
+- `output(data, mode="human", verbose=False)` — router to the correct formatter
+- Modes: `human` (Rich panels/tables), `json`, `plain` (TSV), `markdown`
+- Auto-detects data type (tweet, user, action result, list) and formats accordingly
+
+### `cli.py` — Click CLI
+
+- Root group `cli()` with global options: `-j`, `-p`, `-md`, `-v`, `--min-delay`, `--max-delay`, `--headed`
+- Sub-groups: `tweet`, `user`, `me`
+- Top-level commands: `like`, `retweet`, `login`, `config`
+- `State` dataclass holds mode, verbose, config, and lazy-loaded browser
+- `async_command` decorator bridges async functions into Click's sync world via `asyncio.run()`
+
+---
+
+## X DOM selectors used
+
+These are the key `data-testid` selectors x-browser relies on:
+
+| Selector | Used for |
+|----------|----------|
+| `article[data-testid="tweet"]` | Tweet containers |
+| `div[data-testid="tweetTextarea_0"]` | Compose text box |
+| `button[data-testid="tweetButton"]` | Post/Reply button |
+| `button[data-testid="reply"]` | Reply button on a tweet |
+| `button[data-testid="retweet"]` | Repost button |
+| `button[data-testid="like"]` | Like button (unliked state) |
+| `button[data-testid="unlike"]` | Like button (liked state) |
+| `button[data-testid="bookmark"]` | Bookmark button |
+| `button[data-testid="removeBookmark"]` | Unbookmark button |
+| `button[data-testid="caret"]` | ⋯ more menu on tweet |
+| `div[data-testid="tweetText"]` | Tweet text content |
+| `div[data-testid="User-Name"]` | User display name |
+| `div[data-testid="UserDescription"]` | User bio |
+| `span[data-testid="UserJoinDate"]` | User join date |
+| `a[data-testid="UserUrl"]` | User website link |
+
+If X changes these selectors, update the corresponding functions in `actions.py` and `scrapers.py`.
+
+---
+
+## Adding a new action
+
+1. Add the async function in `actions.py` following the existing pattern
+2. Call `politeness_wait()` as the first line
+3. Add a Click command in `cli.py` under the appropriate group
+4. Return a dict — formatters handle it automatically
+
+## Adding a new scraper
+
+1. Add the async function in `scrapers.py`
+2. Use `_extract_tweet_from_article()` for tweet lists, or write custom extraction
+3. Add a Click command in `cli.py`
+4. Return a dict or list of dicts — formatters handle it automatically
+
+---
+
+## Automation scripts
+
+Located in `scripts/`. Each uses argparse and imports from `x_browser.*`:
+
+| Script | Purpose |
+|--------|---------|
+| `search-and-like.py` | Search & like tweets, scrolling continuously |
+| `search-and-retweet.py` | Search & retweet tweets |
+| `engagement-bot.py` | Search → like + retweet + follow author (each toggleable via `--skip-*`) |
+| `auto-follow-back.py` | Compare followers vs following, follow back the difference |
+| `auto-reply-mentions.py` | Monitor mentions, reply with templates (fixed, file, or defaults) |
+| `scheduled-poster.py` | Post tweets from a text file at intervals |
+
+All scripts support `--headed`, `--min-delay`, `--max-delay`, `--dry-run` (where applicable).
+
+---
+
+## File paths
+
+- Config: `~/.config/x-browser/config.json`
+- Browser session: `~/.config/x-browser/chrome-data/`
+- Source: `src/x_browser/`
+- Scripts: `scripts/`

x_browser-0.1.2/PKG-INFO

@@ -0,0 +1,364 @@
+Metadata-Version: 2.4
+Name: x-browser
+Version: 0.1.2
+Summary: Browser-based CLI for X/Twitter using Playwright + CDP. No API keys needed.
+Project-URL: Homepage, https://github.com/shivamtiwari93/x-browser
+Project-URL: Repository, https://github.com/shivamtiwari93/x-browser
+Project-URL: Issues, https://github.com/shivamtiwari93/x-browser/issues
+Author-email: Shivam Tiwari <shivamtiwari93@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: automation,browser,cli,playwright,twitter,x
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: playwright>=1.40
+Requires-Dist: rich>=13.0
+Description-Content-Type: text/markdown
+
+# x-browser
+
+A CLI and Python module for X/Twitter that works through browser automation — no API keys, no tier restrictions, no rate limits.
+
+Uses [Playwright](https://playwright.dev/) to control your real Chrome installation via CDP. X cannot distinguish this from a human using Chrome.
+
+---
+
+## Quick Start
+
+```bash
+# 1. Install
+git clone https://github.com/shivamtiwari93/x-browser.git
+cd x-browser
+uv tool install .
+
+# 2. Login (one-time — opens Chrome, you log in normally)
+x-browser login
+
+# 3. Use it
+x-browser tweet post 'Hello from x-browser!'
+x-browser tweet search 'AI agents' --max 10
+x-browser like https://x.com/user/status/123
+```
+
+### Install from PyPI
+
+```bash
+pip install x-browser
+# or
+uv tool install x-browser
+```
+
+### Install from Homebrew (macOS)
+
+```bash
+brew tap shivamtiwari93/tap
+brew install x-browser
+```
+
+---
+
+## Why not the API?
+
+| | X API (x-cli) | Browser (x-browser) |
+|---|---|---|
+| **Setup** | 5 API keys from Developer Portal | Log into X once |
+| **Likes** | Removed from Free tier | Works |
+| **Replies** | Restricted on self-serve tiers | Works |
+| **Bookmarks** | Requires Basic+ ($200/mo) | Works |
+| **Post limits** | 500/mo on Free | Normal user limits |
+| **Rate limits** | API rate limiting (429) | None |
+
+---
+
+## CLI Reference
+
+### Tweets
+
+```bash
+x-browser tweet post 'Hello world'
+x-browser tweet post --poll 'Yes,No' 'Do you like polls?'
+x-browser tweet get <id-or-url>
+x-browser tweet delete <id-or-url>
+x-browser tweet reply <id-or-url> 'nice post'
+x-browser tweet quote <id-or-url> 'this is important'
+x-browser tweet search 'machine learning' --max 20
+x-browser tweet metrics <id-or-url>
+```
+
+### Users
+
+```bash
+x-browser user get elonmusk
+x-browser user timeline elonmusk --max 10
+x-browser user followers elonmusk --max 50
+x-browser user following elonmusk
+```
+
+### Self (authenticated user)
+
+```bash
+x-browser me mentions --max 20
+x-browser me bookmarks
+x-browser me bookmark <id-or-url>
+x-browser me unbookmark <id-or-url>
+```
+
+### Quick actions
+
+```bash
+x-browser like <id-or-url>
+x-browser retweet <id-or-url>
+```
+
+### Output formats
+
+```bash
+x-browser -j tweet get <id>        # JSON output
+x-browser -p user get elonmusk     # TSV (pipe to awk/cut)
+x-browser -md tweet get <id>       # Markdown
+x-browser -v tweet get <id>        # Verbose (timestamps, full metrics)
+x-browser --headed tweet post 'hi' # Show browser window
+```
+
+---
+
+## Automation Scripts
+
+Ready-to-run scripts in `scripts/` for long-running tasks:
+
+### Search & Like
+
+Search for tweets and like them continuously:
+
+```bash
+uv run python scripts/search-and-like.py 'YC W26' --hours 5 --headed
+uv run python scripts/search-and-like.py 'AI agents' --hours 8 --min-delay 10 --max-delay 60
+```
+
+### Search & Retweet
+
+Search and retweet matching posts:
+
+```bash
+uv run python scripts/search-and-retweet.py 'AI startups' --hours 3 --headed
+```
+
+### Engagement Bot
+
+Full engagement: search, then like + retweet + follow the author:
+
+```bash
+uv run python scripts/engagement-bot.py 'YC W26' --hours 5 --headed
+uv run python scripts/engagement-bot.py 'AI agents' --skip-follow --hours 3   # like + retweet only
+uv run python scripts/engagement-bot.py 'web3' --skip-retweet --hours 2        # like + follow only
+```
+
+### Auto Follow-Back
+
+Check your followers and follow back anyone you're not already following:
+
+```bash
+uv run python scripts/auto-follow-back.py --headed
+uv run python scripts/auto-follow-back.py --max-check 200 --dry-run   # preview without acting
+```
+
+### Auto Reply Mentions
+
+Monitor your mentions and auto-reply with templates:
+
+```bash
+uv run python scripts/auto-reply-mentions.py --hours 8 --headed
+uv run python scripts/auto-reply-mentions.py --reply 'Thanks for the mention!' --hours 2
+uv run python scripts/auto-reply-mentions.py --replies-file my-replies.txt --hours 12
+```
+
+### Scheduled Poster
+
+Post tweets from a text file on a schedule:
+
+```bash
+# Create a tweets file (one per line, # comments ignored)
+echo 'Hello world!
+Check out x-browser
+# this line is skipped
+Another scheduled tweet' > tweets.txt
+
+uv run python scripts/scheduled-poster.py tweets.txt --interval 3600 --headed     # every hour
+uv run python scripts/scheduled-poster.py tweets.txt --interval 1800 --random-order  # every 30min, shuffled
+uv run python scripts/scheduled-poster.py tweets.txt --interval 600 --loop          # every 10min, loop forever
+```
+
+---
+
+## Use as a Python Module
+
+```python
+import asyncio
+from x_browser.browser import XBrowser
+from x_browser.actions import tweet_post, like, retweet, follow
+from x_browser.scrapers import tweet_search, user_get, user_timeline
+from x_browser.config import Config
+
+async def main():
+    config = Config.load()
+    async with XBrowser(headless=True) as xb:
+        page = xb.page
+
+        # Post a tweet
+        await tweet_post(page, "Hello from Python!", config=config)
+
+        # Search and like
+        tweets = await tweet_search(page, "YC W26", max_results=10)
+        for tweet in tweets:
+            await like(page, tweet["url"], config=config)
+
+        # Follow a user
+        await follow(page, "elonmusk", config=config)
+
+        # Get user profile
+        profile = await user_get(page, "elonmusk")
+        print(profile)
+
+asyncio.run(main())
+```
+
+### Custom delays per call
+
+```python
+await like(page, url, min_delay=5, max_delay=15)
+await tweet_post(page, text, min_delay=0, max_delay=0)  # no delay
+```
+
+### Install as a dependency
+
+```bash
+# In your project
+pip install x-browser
+# or add to pyproject.toml
+# dependencies = ["x-browser"]
+```
+
+```python
+# Then import directly
+from x_browser.browser import XBrowser
+from x_browser.actions import tweet_post
+```
+
+---
+
+## AI Agent Integration
+
+### Claude Code
+
+Add x-browser as a slash command so Claude can use it:
+
+```bash
+# Copy SKILL.md to your Claude commands
+mkdir -p ~/.claude/commands
+cp SKILL.md ~/.claude/commands/x-browser.md
+```
+
+Now Claude Code can use `/x-browser` to see all available commands.
+
+Or add it to a specific project:
+
+```bash
+mkdir -p .claude/commands
+cp /path/to/x-browser/SKILL.md .claude/commands/x-browser.md
+```
+
+### OpenClaw / Other AI Agents
+
+Add the contents of `SKILL.md` to your agent's system prompt or tool configuration. The file is structured so any LLM can parse and use the commands.
+
+### Building with x-browser
+
+If you're building an AI agent that needs X/Twitter capabilities:
+
+```python
+# In your agent's tool implementation
+from x_browser.browser import XBrowser
+from x_browser.actions import tweet_post, like
+from x_browser.scrapers import tweet_search
+
+async def x_post_tool(text: str):
+    async with XBrowser() as xb:
+        return await tweet_post(xb.page, text)
+```
+
+---
+
+## Politeness Delay
+
+Every write action (post, like, retweet, reply, quote, delete, bookmark, follow) waits a random delay before executing. This makes behavior look human.
+
+**Defaults:** 3 – 30 seconds
+
+### Configure
+
+```bash
+# Per-run override
+x-browser --min-delay 5 --max-delay 30 like <url>
+
+# Persistent config
+x-browser config --min-delay 5 --max-delay 30
+
+# View current config
+x-browser config --show
+```
+
+Config is stored in `~/.config/x-browser/config.json`.
+
+---
+
+## How It Works
+
+1. **Chrome launches as a normal process** — no automation flags, no bundled Chromium
+2. **Playwright connects via CDP** (Chrome DevTools Protocol) — passive observer
+3. **Session persists** in `~/.config/x-browser/chrome-data/` — login once, use forever
+4. X sees a real Chrome browser with real cookies — indistinguishable from a human
+
+---
+
+## Troubleshooting
+
+### "Google Chrome not found"
+Install Chrome or set the path. x-browser looks in `/Applications/Google Chrome.app/`.
+
+### Login fails / "Could not log you in"
+Clear the session and try again:
+```bash
+rm -rf ~/.config/x-browser/chrome-data
+x-browser login
+```
+
+### Shell interprets `!` in tweet text
+Use single quotes: `x-browser tweet post 'Hello, World!'`
+
+### `command not found: x-browser`
+Add `~/.local/bin` to your PATH:
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+---
+
+## Acknowledgements
+
+Inspired by [x-cli](https://github.com/Infatoshi/x-cli) by Infatoshi — the API-based counterpart to this project.
+
+## License
+
+MIT