\r \r

God of all Browsers\r

\r A stateful, multi-tab Puppeteer skill designed to help AI agents automate heavily protected websites the exact same way a human does.\r \r It solves three critical AI problems:\r \r

1. Tabs & Statefulness: It launches a single background browser that stays open. Navigations, clicks that open new tabs, and cookies are remembered across multiple commands!\r
2. Vision Abstraction: AI cannot "see" coordinates well, so snapshot maps the DOM, assigns a [tag] ID to every visible button/input, and takes a screenshot. The AI just says "Click tag [15]."\r
3. Bot Evasion: Uses headless: false, custom user agents, removed webdriver footprints, and canvas spoofing.\r \r Important Setup: Ensure the Chromium path is correct (C:\Program Files\Google\Chrome\Application\chrome.exe for Win or /usr/bin/chromium for Linux) and puppeteer-core is installed.\r \r

🚀 COMMANDS & WORKFLOW\r

\r

1. Start the Browser (Required First Step)\r

\r Launch the browser in the background. It will use a persistent chrome_profile directory so you NEVER lose login sessions.\r \r

# Standard mode (Recommended for debugging)\r
node browser.js start\r
\r
# Headless mode (Faster, silent background)\r
# Note: Automatically enabled if running in Termux.\r
node browser.js start --headless\r
```\r
\r
### 2. Take a Snapshot (And auto-close popups)\r
\r
This is your "eyes". Run this before any interaction to get the active window's current state and a list of clickable `[tag]` IDs.\r
\r
```bash\r
# If navigating somewhere new:\r
node browser.js snapshot --url "https://www.google.com"\r
\r
# If already on the page (refresh DOM):\r
node browser.js snapshot\r
```\r
\r
_Wait for this command to output the JSON array of tags._ It will also automatically click away annoying Chatbot/Notification popups.\r
\r
### 3. Click or Type (Like a human)\r
\r
Use the tags captured during the snapshot.\r
\r
```bash\r
# Click a button or link (e.g. tag [24])\r
node browser.js click --tag "[24]"\r
\r
# Type into an input box (e.g. tag [5])\r
node browser.js type --tag "[5]" --text "MERN Stack Developer"\r
\r
# Press a specific keyboard key (Default: Enter)\r
node browser.js press --key "Enter"\r
```\r
\r
### 4. Reading & Content Extraction\r
\r
Extract text content from any element using tags or CSS selectors.\r
\r
```bash\r
# Read visible text from a specific tag\r
node browser.js read --tag "[12]"\r
\r
# Read content of a specific CSS selector (e.g. the main article)\r
node browser.js read --selector "article.main-content"\r
\r
# Deep-expand hidden content (clicks Read More/Show All buttons automatically)\r
node browser.js expand\r
```\r
\r
### 5. Tab Management\r
\r
Many sites open clicked links in a new tab! If your `click` command opens a new tab, the CLI will automatically say:\r
`⚠️ A NEW TAB WAS OPENED!! Automatically switched context to Tab [1].`\r
\r
You can manually manage tabs using:\r
\r
```bash\r
# List all currently open tabs\r
node browser.js check-tabs\r
\r
# Switch to a specific tab index (e.g. going back to the search page: tab 0)\r
node browser.js switch-tab --index 0\r
\r
# Just check the very current URL you are viewing:\r
node browser.js check-url\r
```\r
\r
### 5. Find Tags (Accurate Filtered Search)\r
\r
Use this to filter elements by keywords instead of reading a massive snapshot. It can search live on the current page or in a previously saved JSON file.\r
\r
```bash\r
# Search live for "Apply" or "Success" buttons\r
node browser.js find --query "apply,success"\r
\r
# Search within a specific saved snapshot file (e.g., to verify output)\r
node browser.js find --file "snapshot.json" --query "applied,successfully"\r
```\r
\r
### 6. Refresh Page\r
\r
Manually reload the current tab. Useful for status updates.\r
\r
```bash\r
node browser.js refresh\r
```\r
\r
### 7. Scrape Meta Tags (SEO/OpenGraph)\r
\r
Extract hidden page data like Title, Description, and Social Media tags.\r
\r
```bash\r
node browser.js scrap-meta\r
```\r
\r
### 8. Dynamic Evolution (Eval)\r
\r
Execute custom JavaScript logic directly in the browser context. **Note: For security, the `--force` flag is required.** Supports both inline code and script files.\r
\r
```bash\r
# Execute inline code (Requires --force)\r
node browser.js eval --code "return { links: document.querySelectorAll('a').length }" --force\r
\r
# Execute from a file (Requires --force)\r
node browser.js eval --file "custom_script.js" --force\r
```\r
\r
### 9. Google Search (Direct Extraction)\r
\r
Get the top 5 organic search results (Titles, Links, Snippets) in a single command. Extremely fast and agent-friendly.\r
\r
```bash\r
node browser.js google --query "Mathanraj Murugesan"\r
```\r
\r
### 10. Session & Learning\r
\r
Manage your login state and keep track of automation failures for self-correction.\r
\r
```bash\r
# Save current cookies to session.json (persists across runs)\r
node browser.js save-session\r
\r
# Check if the page requires login or if the user already logged in\r
node browser.js auth-status\r
\r
# Log a failure and a lesson learned for AI self-correction\r
node browser.js log-learning --failed "Selector [12] was hidden" --fixed "Used [expand] first" --lessons "Always try expanding content before reading"\r
```\r
\r
### 11. Stop the Browser\r
\r
Clean up resources when the task is entirely finished.\r
\r
```bash\r
node browser.js stop\r
```\r
\r
## 🧠 AI STRATEGY (HOW TO USE)\r
\r
1. Run `start`.\r
2. Run `snapshot --url "[TARGET]"`.\r
3. Check `auth-status` if the page is restricted. Use `save-session` after manual/automated login.\r
4. Analyze the output tags. Think step-by-step. Does the page require a search? Does it require clicking an 'Apply' button?\r
5. Run `click` or `type` on the specific `[tag]`.\r
6. **READ THE CLICK OUTPUT CAREFULLY!** Did it say a new tab opened? If so, your next `snapshot` will read from that tab.\r
7. Run `snapshot` again WITHOUT a URL to read the new page/modal that loaded.\r
8. Repeat until the task is complete. If you need to return to the search results, run `check-tabs` and `switch-tab --index 0`.\r
9. If you encounter a bug (e.g., selector not found), use `log-learning` to record the fix for future runs.\r
10. If you need to run custom JS, use `eval` with the `--force` flag.\r
11. Once finished, run `stop`.\r
\r
### 10. Common Extraction Patterns (USE EVAL)\r
\r
When you need to get actual data (not just see the page), use the `eval` command with these patterns:\r
\r
**Google Search Results:**\r
\r
```bash\r
node browser.js eval --force --code "return Array.from(document.querySelectorAll('div.g')).slice(0,5).map(g => ({ title: g.querySelector('h3')?.innerText, link: g.querySelector('a')?.href }))"\r
```\r
\r
**LinkedIn Profile (Basic):**\r
\r
```bash\r
node browser.js eval --force --code "return { name: document.querySelector('.text-heading-xlarge')?.innerText, title: document.querySelector('.text-body-medium')?.innerText }"\r
```\r
\r
**General Link Scraper:**\r
\r
```bash\r
node browser.js eval --force --code "return Array.from(document.querySelectorAll('a')).map(a => ({ text: a.innerText, url: a.href })).filter(a => a.url.startsWith('http'))"\r
```\r
\r
### 11. Robust Automation Workflow (Multi-Tab & State)\r
\r
Follow this professional flow for complex, multi-stage automation tasks:\r
\r
1.  **Initialize**: Run `start` to launch the persistent browser instance.\r
2.  **Navigation & Auth**: \r
    - Run `snapshot --url "[TARGET]"` to land on the page.\r
    - Run `auth-status` to check if a login is required.\r
    - If you perform a manual/auto login, run `save-session` to persist the state.\r
3.  **Clean & Expand**: \r
    - Always run `expand` before deep scanning. This removes popups and reveals hidden content that might be missing from the DOM.\r
4.  **Action Loop**:\r
    - Run `snapshot` (without URL) to get the latest `[tag]` list.\r
    - Perform interactions using `click`, `type`, or `press`.\r
    - **Pro Tip**: If a click result is ambiguous, run `check-url` to see if the page changed.\r
5.  **Multi-Tab Handling**:\r
    - If the terminal warns `⚠️ A NEW TAB WAS OPENED`, run `check-tabs`.\r
    - Note the index of the new tab (e.g., `[1]`) and run `switch-tab --index 1`.\r
    - Every snapshot and command thereafter will target this new tab.\r
6.  **Extraction**:\r
    - Use `read --tag "[#]"` for simple text.\r
    - Use `eval` for complex data structures (arrays of objects, etc.).\r
7.  **Recovery & Learning**:\r
    - If a command fails, use `log-learning --failed "..." --fixed "..."` to document the solution for the AI's internal memory.\r
8.  **Teardown**: Run `stop` only when the entire job (across all domains) is finished.\r