browserforce 1.0.5 → 1.0.7

package/README.md

@@ -1,6 +1,8 @@
-# BrowserForce
+# BrowserForce // 
 
 > "a lion doesn't concern itself with token counting" — [@steipete](https://x.com/steipete), creator of [OpenClaw](https://github.com/openclaw/openclaw)
+>
+> "a 10x user doesn't concern itself with sandboxed browsers // sandboxes are for kids" — BrowserForce, your friendly neighborhood power source.
 
 **You're giving an AI your real Chrome — your logins, cookies, and sessions. That takes conviction.** BrowserForce is built for people who use the best models and don't look back. Security is built in: lock URLs, block navigation, read-only mode, auto-cleanup — you stay in control.
 
@@ -10,15 +12,16 @@ Works with [OpenClaw](https://github.com/openclaw/openclaw), Claude, or any MCP-
 
 ## Comparison
 
-| | Playwright MCP | Playwriter | Claude Extension | Antigravity | BrowserForce |
+| | Playwright MCP | OpenClaw Browser | Playwriter | Claude Extension | BrowserForce |
 |---|---|---|---|---|---|
-| Tab access | N/A (new browser) | Click each tab | Click each tab | Click each tab | **All tabs, automatic** |
-| Browser | Spawns new Chrome | Your Chrome | Your Chrome | Your Chrome | **Your Chrome** |
-| Autonomous | Yes | No (manual click) | No (manual click) | No (manual click) | **Yes (fully autonomous)** |
-| Tools | Many dedicated tools | 1 `execute` tool | Built-in | Many dedicated tools | **1 `execute` tool** |
-| Agent support | Any MCP client | Any MCP client | Claude only | Custom | **Any MCP client** |
-| Context method | Screenshots | A11y snapshots | Screenshots | Screenshots | **A11y snapshots** |
-| Playwright API | Partial | Full | No | No | **Full** |
+| Browser | Spawns new Chrome | Separate profile | Your Chrome | Your Chrome | **Your Chrome** |
+| Login state | Fresh | Fresh (isolated) | Yours | Yours | **Yours** |
+| Tab access | N/A (new browser) | Managed by agent | Click each tab | Click each tab | **All tabs, automatic** |
+| Autonomous | Yes | Yes | No (manual click) | No (manual click) | **Yes (fully autonomous)** |
+| Context method | Screenshots (100KB+) | Screenshots + snapshots | A11y snapshots (5-20KB) | Screenshots (100KB+) | **A11y snapshots (5-20KB)** |
+| Tools | Many dedicated | 1 `browser` tool | 1 `execute` tool | Built-in | **1 `execute` tool** |
+| Agent support | Any MCP client | OpenClaw only | Any MCP client | Claude only | **Any MCP client** |
+| Playwright API | Partial | No | Full | No | **Full** |
 
 ## Setup
 
@@ -43,41 +46,44 @@ pnpm install
 3. Click **Load unpacked** → select the `extension/` folder
 4. Extension icon appears in your toolbar (gray = disconnected)
 
-### 3. Start the relay
+### 3. Done
 
-```bash
-browserforce serve
-```
+The relay auto-starts when you run any command or connect via MCP — no manual step needed. Extension icon turns green once connected.
 
-Or with pnpm (development):
+To run the relay manually (optional):
 
 ```bash
-pnpm relay
-```
-
-```
-  BrowserForce
-  ────────────────────────────────────────
-  Status:   http://127.0.0.1:19222/
-  CDP:      ws://127.0.0.1:19222/cdp?token=<TOKEN>
-  ────────────────────────────────────────
+browserforce serve
 ```
 
-Extension icon turns green — you're connected.
-
 ## Connect Your Agent
 
 ### OpenClaw
 
-Install the BrowserForce skill:
+Most OpenClaw users chat with their agent from Telegram or WhatsApp. BrowserForce lets your agent browse the web as you — no login flows, no captchas — even from a messaging app.
+
+**Quick setup** (copy-paste into your terminal):
 
 ```bash
-npx -y skills add ivalsaraj/browserforce
+npm install -g browserforce && npx -y skills add ivalsaraj/browserforce
 ```
 
-The skill teaches your agent to use BrowserForce CLI commands via Bash. Your OpenClaw agent can now browse the web as you — no login flows, no captchas.
+Then start the relay (keep this running):
 
-Or add BrowserForce as an MCP server in `~/.openclaw/openclaw.json`:
+```bash
+browserforce serve
+```
+
+**Verify it works** — send this to your agent:
+
+> Go to https://x.com and give me top tweets
+
+If your agent browses to the page and responds with the title, you're all set.
+
+<details>
+<summary><b>Alternative: MCP server</b> (advanced)</summary>
+
+If you prefer MCP over the skill, add to `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -101,6 +107,8 @@ Or add BrowserForce as an MCP server in `~/.openclaw/openclaw.json`:
 }
 ```
 
+</details>
+
 ### Claude Desktop
 
 Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
@@ -202,8 +210,137 @@ state.results = await page.evaluate(() => document.title);
 | Tool | Description |
 |------|-------------|
 | `execute` | Run Playwright JavaScript in your real Chrome. Access `page`, `context`, `state`, `snapshot()`, `waitForPageLoad()`, `getLogs()`, and Node.js globals. |
+| `screenshot_with_labels` | Take a screenshot with Vimium-style accessibility labels overlaid on interactive elements. |
 | `reset` | Reconnect to the relay and clear state. Use when the connection drops. |
 
+## Examples
+
+Get started with simple prompts. The AI generates code and does the work.
+
+<details>
+<summary><b>Example 1: Read page content (X.com search)</b></summary>
+
+**Prompt to AI:**
+> Go to x.com/search and search for "browserforce". Show me the top 5 tweets you find.
+
+**What the AI does:** Navigates to X, searches the term, extracts top tweets, returns them to you.
+
+**Use case:** Quick research, trend tracking, social listening.
+
+</details>
+
+<details>
+<summary><b>Example 2: Interact with a form (GitHub search)</b></summary>
+
+**Prompt to AI:**
+> Go to GitHub and search for "ai agents". Show me the top 3 repositories and their star counts.
+
+**What the AI does:** Fills GitHub search, waits for results, extracts repo names + stars, returns them.
+
+**Use case:** Finding libraries, competitive research, project discovery.
+
+</details>
+
+### Multi-Tab Workflows
+
+<details>
+<summary><b>Example 3: Search → Extract → Return</b></summary>
+
+**Prompt to AI:**
+> Search ProductHunt for "AI tools" and give me the top 5 products with their taglines and upvote counts.
+
+**What the AI does:** Navigates ProductHunt, searches, extracts product info, returns structured data.
+
+**Use case:** Market research, finding tools, competitive analysis.
+
+</details>
+
+<details>
+<summary><b>Example 4: Open result in new tab, process there</b></summary>
+
+**Prompt to AI:**
+> Find the #1 product from your last ProductHunt search, click into it, and read the full description. Tell me what it does.
+
+**What the AI does:** Opens the product page from previous results, reads the description, summarizes it.
+
+**Use case:** Deep-dive research, understanding competitors, due diligence.
+
+</details>
+
+<details>
+<summary><b>Example 5: Debugging workflow (inspect + verify)</b></summary>
+
+**Prompt to AI:**
+> Go to my staging site at staging.myapp.com/checkout and take a labeled screenshot. Tell me if the "Complete Purchase" button is visible and what's around it.
+
+**What the AI does:** Navigates, takes screenshot with interactive labels, analyzes button state and layout.
+
+**Use case:** Visual debugging, QA checks, spotting broken elements.
+
+</details>
+
+<details>
+<summary><b>Example 6: Test form with data</b></summary>
+
+**Prompt to AI:**
+> Sign up for Substack using the email test.user@example.com. Tell me if the signup completes successfully.
+
+**What the AI does:** Fills the form, submits, waits for confirmation, reports success/failure.
+
+**Use case:** Testing sign-up flows, QA automation, form validation.
+
+</details>
+
+<details>
+<summary><b>Example 7: Content pipeline (search → extract → compare)</b></summary>
+
+**Prompt to AI:**
+> Search for "AI regulation" on both X.com and LinkedIn. Give me the top 5 trending posts from each and tell me which topics overlap.
+
+**What the AI does:** Searches both platforms, extracts posts, compares content, returns analysis.
+
+**Use case:** Multi-source research, trend analysis, market sentiment.
+
+</details>
+
+<details>
+<summary><b>Example 8: Data extraction → CSV pipeline</b></summary>
+
+**Prompt to AI:**
+> Go to Hacker News and extract the top 10 stories with their titles and vote counts. Format as CSV so I can import into a spreadsheet.
+
+**What the AI does:** Navigates HN, extracts story data, formats as CSV, returns it ready to paste.
+
+**Use case:** Data workflows, trend tracking, content curation.
+
+</details>
+
+<details>
+<summary><b>Example 9: A/B testing across variants</b></summary>
+
+**Prompt to AI:**
+> Visit myapp.com/?variant=red and myapp.com/?variant=blue. Compare the two designs and tell me which button color is more prominent and what other differences exist.
+
+**What the AI does:** Opens both variants, compares layouts/colors/text, reports visual differences.
+
+**Use case:** Design QA, A/B testing, variant comparison.
+
+</details>
+
+<details>
+<summary><b>Example 10: Monitor + alert workflow</b></summary>
+
+**Prompt to AI:**
+> Check our status page at status.myapp.com every few minutes. Tell me the current status of the API and database. Alert me if anything changes from green to red.
+
+**What the AI does:** Monitors status page, reads indicators, alerts on degradation.
+
+**Use case:** Uptime monitoring, incident detection, SLA tracking.
+
+</details>
+
+**More examples** and detailed walkthrough available in the [User Guide](GUIDE.md#examples).
+
 ## How It Works
 
 ```

package/bin.js

@@ -43,7 +43,8 @@ function httpGet(url) {
 }
 
 async function connectBrowser() {
-  const { getCdpUrl } = await import('./mcp/src/exec-engine.js');
+  const { getCdpUrl, ensureRelay } = await import('./mcp/src/exec-engine.js');
+  await ensureRelay();
   // playwright-core lives in mcp/node_modules (pnpm workspace sub-package).
   // Use createRequire from the mcp package context to locate it, then dynamic-import.
   const { createRequire } = await import('node:module');

package/mcp/src/exec-engine.js

@@ -4,6 +4,8 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { spawn } from 'node:child_process';
 import {
   TEST_ID_ATTRS,
   buildSnapshotText, parseSearchPattern, annotateStableAttrs,
@@ -11,8 +13,10 @@ import {
 
 // ─── Configuration ───────────────────────────────────────────────────────────
 
+const DEFAULT_PORT = 19222;
 export const BF_DIR = join(homedir(), '.browserforce');
 export const CDP_URL_FILE = join(BF_DIR, 'cdp-url');
+const RELAY_SCRIPT = fileURLToPath(new URL('../../relay/src/index.js', import.meta.url));
 
 export function getCdpUrl() {
   if (process.env.BF_CDP_URL) return process.env.BF_CDP_URL;
@@ -34,10 +38,59 @@ export function getRelayHttpUrl() {
     const parsed = new URL(cdpUrl);
     return `http://${parsed.hostname}:${parsed.port}`;
   } catch {
-    return 'http://127.0.0.1:19222';
+    return `http://127.0.0.1:${DEFAULT_PORT}`;
   }
 }
 
+// ─── Auto-start relay ───────────────────────────────────────────────────────
+
+function getRelayPort() {
+  if (process.env.RELAY_PORT) return parseInt(process.env.RELAY_PORT, 10);
+  try {
+    const url = readFileSync(CDP_URL_FILE, 'utf8').trim();
+    if (url) {
+      const port = new URL(url).port;
+      if (port) return parseInt(port, 10);
+    }
+  } catch { /* fall through */ }
+  return DEFAULT_PORT;
+}
+
+async function isRelayRunning(port) {
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/`, {
+      signal: AbortSignal.timeout(500),
+    });
+    return res.ok;
+  } catch { return false; }
+}
+
+/**
+ * Ensure the relay server is running. If not, spawn it as a detached
+ * background process and wait for it to become reachable.
+ */
+export async function ensureRelay() {
+  const port = getRelayPort();
+  if (await isRelayRunning(port)) return;
+
+  const child = spawn(process.execPath, [RELAY_SCRIPT], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, RELAY_PORT: String(port) },
+  });
+  child.unref();
+
+  const deadline = Date.now() + 5000;
+  while (Date.now() < deadline) {
+    await new Promise(r => setTimeout(r, 200));
+    if (await isRelayRunning(port)) {
+      process.stderr.write('[browserforce] Relay auto-started\n');
+      return;
+    }
+  }
+  throw new Error('Failed to auto-start relay server within 5s');
+}
+
 // ─── Smart Page Load Detection ───────────────────────────────────────────────
 // Filters analytics/ad requests that never finish, polls document.readyState +
 // pending resource count.

package/mcp/src/index.js

@@ -7,7 +7,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { chromium } from 'playwright-core';
 import {
-  getCdpUrl, CodeExecutionTimeoutError, buildExecContext, runCode, formatResult,
+  getCdpUrl, ensureRelay, CodeExecutionTimeoutError, buildExecContext, runCode, formatResult,
 } from './exec-engine.js';
 import { screenshotWithLabels } from './a11y-labels.js';
 
@@ -65,6 +65,7 @@ let browser = null;
 
 async function ensureBrowser() {
   if (browser?.isConnected()) return;
+  await ensureRelay();
   const cdpUrl = getCdpUrl();
   browser = await chromium.connectOverCDP(cdpUrl);
   browser.on('disconnected', () => {

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "browserforce",
-  "version": "1.0.5",
+  "version": "1.0.7",
   "type": "module",
-  "description": "Give AI agents your real Chrome browser — your logins, cookies, and tabs. Works with OpenClaw, Claude, and any MCP agent.",
+  "description": "Give AI agents your real Chrome browser with progressive examples: simple reads, form interactions, multi-tab workflows, and state persistence. Search X and GitHub, extract ProductHunt data, test forms, compare A/B variants, monitor status pages. Works with OpenClaw, Claude, and any MCP agent.",
   "homepage": "https://github.com/ivalsaraj/browserforce",
   "repository": {
     "type": "git",

package/skills/browserforce/SKILL.md

@@ -19,8 +19,8 @@ cookies, and extensions already active. No headless browser, no fresh profiles.
 ## Prerequisites
 
 The user must have:
-1. BrowserForce relay running: `browserforce serve`
-2. BrowserForce Chrome extension installed and connected (green icon)
+1. BrowserForce Chrome extension installed and connected (green icon)
+2. The relay auto-starts on first command — no manual step needed
 
 Check with: `browserforce status`