From 188d1dff49ea4d8ef7da1ade9031cf8a5803f3a8 Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Sun, 25 Jan 2026 03:00:23 +0000 Subject: [PATCH 1/2] feat(browser): add playwright-cli subagent for AI agent automation - Add playwright-cli.md subagent with Microsoft official CLI documentation - Update browser-automation.md decision tree to include playwright-cli - Update README.md with playwright-cli in browser tools section - Recommend bun install for faster package installation playwright-cli is Microsoft's official CLI for AI agents, part of @playwright/mcp. Key features: --session isolation, built-in tracing, ref-based element targeting. --- .agent/tools/browser/browser-automation.md | 100 ++++-- .agent/tools/browser/playwright-cli.md | 344 +++++++++++++++++++++ README.md | 44 +-- 3 files changed, 442 insertions(+), 46 deletions(-) create mode 100644 .agent/tools/browser/playwright-cli.md diff --git a/.agent/tools/browser/browser-automation.md b/.agent/tools/browser/browser-automation.md index 8fb4b8cff2..d74333204e 100644 --- a/.agent/tools/browser/browser-automation.md +++ b/.agent/tools/browser/browser-automation.md @@ -24,7 +24,8 @@ Most tools run **headless by default** (no visible window, no mouse/keyboard com 1. Fastest tool that meets requirements 2. ARIA snapshots over screenshots for AI understanding (50-200 tokens vs ~1K) 3. Headless over headed (no mouse/window competition) -4. Playwright direct as default unless a specific feature is needed elsewhere +4. CLI tools (playwright-cli, agent-browser) for AI agents - simpler tool restriction +5. Playwright direct for TypeScript projects needing full API control ```text What do you need? @@ -48,13 +49,13 @@ What do you need? | +-> Need parallel isolated sessions? | | | | | +-> Maximum speed? --> Playwright (5 contexts in 2.1s) - | | +-> CLI/shell scripting? --> agent-browser --session (3 in 2.0s) + | | +-> CLI/shell scripting? --> playwright-cli or agent-browser --session | | +-> Extraction parallel? --> Crawl4AI arun_many (1.7x speedup) | | | +-> Need persistent login across sessions? | | | | | +-> With extensions? --> dev-browser (profile persists) - | | +-> Without extensions? --> Playwright storageState or dev-browser + | | +-> Without extensions? --> playwright-cli (session profiles) or Playwright storageState | | | +-> Need proxy / VPN / residential IP? | | | @@ -65,6 +66,10 @@ What do you need? | +-> Unknown page structure / self-healing? | | --> Stagehand (natural language, adapts to changes, slowest) | | + | +-> AI agent (CLI-first, simple tool restriction)? + | | --> playwright-cli (Microsoft official, `Bash(playwright-cli:*)`) + | | --> agent-browser (Vercel, more CLI commands, Rust binary) + | | | +-> None of the above (just fast automation)? | --> Playwright direct (fastest, 0.9s form fill) | @@ -93,7 +98,7 @@ What do you need? +-> Need to stay logged in across restarts? --> dev-browser (profile) +-> Need parallel test contexts? --> Playwright (isolated contexts) +-> Need visual debugging? --> dev-browser (headed) + DevTools MCP - +-> CI/CD pipeline? --> Playwright or agent-browser + +-> CI/CD pipeline? --> playwright-cli, agent-browser, or Playwright ``` **AI page understanding** (how the AI "sees" the page): @@ -130,34 +135,37 @@ Tested 2026-01-24, macOS ARM64 (Apple Silicon), headless, warm daemon. Median of ## Feature Matrix -| Feature | Playwright | dev-browser | agent-browser | Crawl4AI | WaterCrawl | Playwriter | Stagehand | -|---------|-----------|-------------|---------------|----------|------------|------------|-----------| -| **Headless** | Yes | Yes | Yes (default) | Yes | Cloud API | No (your browser) | Yes | -| **Session persistence** | storageState | Profile dir | state save/load | user_data_dir | API sessions | Your browser | Per-instance | -| **Cookie management** | Full API | Persistent | CLI commands | Persistent | Via API | Your browser | Per-instance | -| **Proxy support** | Full | Via launch args | No | Full (ProxyConfig) | Datacenter+Residential | Your browser | Via args | -| **SOCKS5/VPN** | Yes | Possible | No | Yes | No | Your browser | Via args | -| **Browser extensions** | Yes (persistent ctx) | Yes (profile) | No | No | No | Yes (yours) | Possible | -| **Multi-session** | Per-context | Named pages | --session flag | Per-crawl | Per-request | Per-tab | Per-instance | -| **Form filling** | Full API | Full API | CLI fill/click | No | No | Full API | Natural language | -| **Screenshots** | Full API | Full API | CLI command | Built-in | PDF/Screenshot | Full API | Via page | -| **Data extraction** | evaluate() | evaluate() | eval command | CSS/XPath/LLM | Markdown/JSON | evaluate() | extract() + schema | -| **Natural language** | No | No | No | LLM extraction | No | No | act/extract/observe | -| **Self-healing** | No | No | No | No | No | No | Yes | -| **AI-optimized output** | No | ARIA snapshots | Snapshot + refs | Markdown/JSON | Markdown/JSON | No | Structured schemas | -| **Web search** | No | No | No | No | Yes | No | No | -| **Sitemap generation** | No | No | No | No | Yes | No | No | -| **Anti-detect** | rebrowser-patches | Via launch args | No | No | No | Your browser | Via Playwright | -| **Fingerprint rotation** | No (add Camoufox) | No | No | No | No | No | No | -| **Multi-profile** | storageState dirs | Profile dir | --session | user_data_dir | N/A | No | No | -| **Setup required** | npm install | Server running | npm install | pip/Docker | API key | Extension click | npm + API key | -| **Interface** | JS/TS API | TS scripts | CLI | Python API | REST/SDK | JS API | JS/Python SDK | +| Feature | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | WaterCrawl | Playwriter | Stagehand | +|---------|-----------|----------------|-------------|---------------|----------|------------|------------|-----------| +| **Headless** | Yes | Yes (default) | Yes | Yes (default) | Yes | Cloud API | No (your browser) | Yes | +| **Session persistence** | storageState | Profile dir | Profile dir | state save/load | user_data_dir | API sessions | Your browser | Per-instance | +| **Cookie management** | Full API | Persistent | Persistent | CLI commands | Persistent | Via API | Your browser | Per-instance | +| **Proxy support** | Full | No | Via launch args | No | Full (ProxyConfig) | Datacenter+Residential | Your browser | Via args | +| **SOCKS5/VPN** | Yes | No | Possible | No | Yes | No | Your browser | Via args | +| **Browser extensions** | Yes (persistent ctx) | No | Yes (profile) | No | No | No | Yes (yours) | Possible | +| **Multi-session** | Per-context | --session flag | Named pages | --session flag | Per-crawl | Per-request | Per-tab | Per-instance | +| **Form filling** | Full API | CLI fill/type | Full API | CLI fill/click | No | No | Full API | Natural language | +| **Screenshots** | Full API | CLI command | Full API | CLI command | Built-in | PDF/Screenshot | Full API | Via page | +| **Data extraction** | evaluate() | eval command | evaluate() | eval command | CSS/XPath/LLM | Markdown/JSON | evaluate() | extract() + schema | +| **Natural language** | No | No | No | No | LLM extraction | No | No | act/extract/observe | +| **Self-healing** | No | No | No | No | No | No | No | Yes | +| **AI-optimized output** | No | Snapshot + refs | ARIA snapshots | Snapshot + refs | Markdown/JSON | Markdown/JSON | No | Structured schemas | +| **Tracing** | Full API | Built-in CLI | Via Playwright | Via Playwright | No | No | Via CDP | Via Playwright | +| **Web search** | No | No | No | No | No | Yes | No | No | +| **Sitemap generation** | No | No | No | No | No | Yes | No | No | +| **Anti-detect** | rebrowser-patches | No | Via launch args | No | No | No | Your browser | Via Playwright | +| **Fingerprint rotation** | No (add Camoufox) | No | No | No | No | No | No | No | +| **Multi-profile** | storageState dirs | --session | Profile dir | --session | user_data_dir | N/A | No | No | +| **Setup required** | npm install | npm install -g | Server running | npm install | pip/Docker | API key | Extension click | npm + API key | +| **Interface** | JS/TS API | CLI | TS scripts | CLI | Python API | REST/SDK | JS API | JS/Python SDK | +| **Maintainer** | Microsoft | Microsoft | Community | Vercel | Community | WaterCrawl | Community | Browserbase | ## Quick Reference | Tool | Best For | Speed | Setup | |------|----------|-------|-------| | **Playwright** | Raw speed, full control, proxy support | Fastest | `npm i playwright` | +| **playwright-cli** | AI agents, CLI automation, session isolation | Fast | `bun i -g @playwright/mcp` | | **dev-browser** | Persistent sessions, dev testing, TypeScript | Fast | `dev-browser-helper.sh setup && start` | | **agent-browser** | CLI/CI/CD, AI agents, parallel sessions | Fast (warm) | `agent-browser-helper.sh setup` | | **Crawl4AI** | Web scraping, bulk extraction, structured data | Fast | `pip install crawl4ai` (venv) | @@ -279,6 +287,46 @@ const context = await browser.newContext({ storageState: 'state.json' }); **Persistence**: Use `storageState` to save/load cookies and localStorage across sessions. +### Playwright CLI (AI Agents) + +Best for: AI agent automation, CLI-first workflows, session isolation, Microsoft-maintained. + +```bash +# Install (bun preferred for speed) +bun install -g @playwright/mcp@latest + +# Basic workflow +playwright-cli open https://example.com +playwright-cli snapshot # Get accessibility tree with refs +playwright-cli click e2 # Click by ref (note: no @ prefix) +playwright-cli fill e3 "user@example.com" # Fill by ref +playwright-cli type "search query" # Type into focused element +playwright-cli screenshot +playwright-cli close + +# Parallel sessions +playwright-cli --session=s1 open https://site-a.com +playwright-cli --session=s2 open https://site-b.com +playwright-cli session-list + +# Tracing for debugging +playwright-cli tracing-start +playwright-cli click e4 +playwright-cli fill e7 "test" +playwright-cli tracing-stop +``` + +**Persistence**: Sessions preserve cookies/storage between calls. Use `--session=name` for isolation. + +**vs agent-browser**: Simpler ref syntax (`e5` vs `@e5`), built-in tracing, Microsoft-maintained. agent-browser has Rust CLI for faster cold starts and more commands. + +**Skill installation** (Claude Code): + +```bash +/plugin marketplace add microsoft/playwright-cli +/plugin install playwright-cli +``` + ### Dev-Browser (Persistent Profile) Best for: Development testing, staying logged in across sessions, TypeScript projects. diff --git a/.agent/tools/browser/playwright-cli.md b/.agent/tools/browser/playwright-cli.md new file mode 100644 index 0000000000..faafd64abb --- /dev/null +++ b/.agent/tools/browser/playwright-cli.md @@ -0,0 +1,344 @@ +--- +description: Playwright CLI - headless browser automation CLI designed for AI agents (Microsoft official) +mode: subagent +tools: + read: true + write: false + edit: false + bash: true + glob: true + grep: true + webfetch: true + task: true +--- + +# Playwright CLI - Browser Automation for AI Agents + + + +## Quick Reference + +- **Purpose**: Headless browser automation CLI designed specifically for AI agents +- **Install**: `npm install -g @playwright/mcp@latest` +- **GitHub**: https://github.com/microsoft/playwright-cli +- **Skill**: Available as Claude Code skill via `/plugin marketplace add microsoft/playwright-cli` + +**Core Workflow** (optimal for AI): + +```bash +playwright-cli open https://example.com +playwright-cli snapshot # Get accessibility tree with refs +playwright-cli click e2 # Click by ref from snapshot +playwright-cli fill e3 "test@example.com" # Fill by ref +playwright-cli type "search query" # Type into focused element +playwright-cli screenshot +playwright-cli close +``` + +**Key Advantages**: + +- **Microsoft official**: Part of `@playwright/mcp`, actively maintained +- **Ref-based selection**: Deterministic element targeting from snapshots (e1, e2, e3) +- **Session isolation**: `--session` flag for parallel browser instances +- **Headless by default**: Use `--headed` only for visual debugging +- **Persistent profiles**: Sessions preserve cookies/storage between calls +- **Tracing built-in**: `tracing-start/stop` for debugging +- **No MCP overhead**: Direct CLI calls, no WebSocket relay + +**Performance**: Similar to agent-browser (both use Playwright engine). Navigate+screenshot ~1.9s, form fill ~1.4s. + +**vs agent-browser**: playwright-cli uses simpler ref syntax (`e5` vs `@e5`), has built-in tracing, and is Microsoft-maintained. agent-browser has Rust CLI for faster cold starts. + +**vs Playwriter MCP**: playwright-cli runs headless with isolated sessions. Playwriter uses your existing browser (headed, with your extensions/passwords). + +**When to use**: + +- AI agent automation (forms, clicks, navigation) +- CI/CD pipelines and shell scripts +- Parallel browser sessions +- Tasks that don't need your existing browser state + + + +## Installation + +```bash +# Install globally (recommended - fastest, no runner overhead) +bun install -g @playwright/mcp@latest # Bun (preferred) +npm install -g @playwright/mcp@latest # npm alternative + +# Verify installation +playwright-cli --help + +# Or run without global install (slower cold start) +bunx @playwright/mcp playwright-cli --help # ~0.3s +npx @playwright/mcp playwright-cli --help # ~2-3s (registry lookup) +``` + +**As Claude Code skill** (recommended for Claude Code users): + +```bash +/plugin marketplace add microsoft/playwright-cli +/plugin install playwright-cli +``` + +**Manual skill installation**: + +```bash +mkdir -p .claude/skills/playwright-cli +curl -o .claude/skills/playwright-cli/SKILL.md \ + https://raw.githubusercontent.com/microsoft/playwright-cli/main/skills/playwright-cli/SKILL.md +``` + +## Core Workflow + +### The Snapshot + Ref Pattern + +This is the **recommended workflow for AI agents**: + +```bash +# 1. Navigate and get snapshot +playwright-cli open https://example.com +playwright-cli snapshot + +# 2. AI identifies target refs from snapshot +# Output includes refs like: +# - heading "Example Domain" [ref=e1] [level=1] +# - button "Submit" [ref=e2] +# - textbox "Email" [ref=e3] + +# 3. Execute actions using refs +playwright-cli click e2 +playwright-cli fill e3 "input text" + +# 4. Get new snapshot if page changed +playwright-cli snapshot +``` + +**Why use refs?** + +- **Deterministic**: Ref points to exact element from snapshot +- **Fast**: No DOM re-query needed +- **AI-friendly**: Snapshot + ref workflow is optimal for LLMs + +## Commands Reference + +### Core + +```bash +playwright-cli open # Navigate to URL +playwright-cli close # Close the page +playwright-cli type # Type text into focused/editable element +playwright-cli click [button] # Click element (left/right/middle) +playwright-cli dblclick [button] # Double-click element +playwright-cli fill # Clear and fill input +playwright-cli drag # Drag and drop between elements +playwright-cli hover # Hover over element +playwright-cli select # Select dropdown option +playwright-cli upload # Upload file(s) +playwright-cli check # Check checkbox/radio +playwright-cli uncheck # Uncheck checkbox +playwright-cli snapshot # Get accessibility tree with refs +playwright-cli eval [ref] # Evaluate JavaScript +playwright-cli dialog-accept [prompt] # Accept dialog (with optional prompt text) +playwright-cli dialog-dismiss # Dismiss dialog +playwright-cli resize # Resize browser window +``` + +### Navigation + +```bash +playwright-cli go-back # Navigate back +playwright-cli go-forward # Navigate forward +playwright-cli reload # Reload page +``` + +### Keyboard + +```bash +playwright-cli press # Press key (Enter, ArrowDown, Tab, etc.) +playwright-cli keydown # Press key down +playwright-cli keyup # Release key +``` + +### Mouse + +```bash +playwright-cli mousemove # Move mouse to position +playwright-cli mousedown [button] # Press mouse button +playwright-cli mouseup [button] # Release mouse button +playwright-cli mousewheel # Scroll mouse wheel +``` + +### Save As + +```bash +playwright-cli screenshot # Screenshot current page +playwright-cli screenshot # Screenshot specific element +playwright-cli pdf # Save page as PDF +``` + +### Tabs + +```bash +playwright-cli tab-list # List all tabs +playwright-cli tab-new [url] # Create new tab +playwright-cli tab-close [index] # Close tab +playwright-cli tab-select # Switch to tab +``` + +### DevTools + +```bash +playwright-cli console [min-level] # List console messages +playwright-cli network # List network requests +playwright-cli run-code # Run Playwright code snippet +playwright-cli tracing-start # Start trace recording +playwright-cli tracing-stop # Stop trace recording +``` + +### Sessions + +```bash +playwright-cli --session=name open # Use named session +playwright-cli session-list # List all sessions +playwright-cli session-stop [name] # Stop session +playwright-cli session-stop-all # Stop all sessions +playwright-cli session-delete [name] # Delete session data and profile +``` + +## Sessions + +Playwright CLI uses persistent profiles by default. Cookies and storage are preserved between calls. + +### Named Sessions + +Run multiple isolated browser instances: + +```bash +# Different sessions for different tasks +playwright-cli open https://playwright.dev +playwright-cli --session=example open https://example.com +playwright-cli session-list + +# Work in specific session +playwright-cli --session=example click e4 +playwright-cli --session=example snapshot +``` + +### Environment Variable + +Set session via environment for all commands: + +```bash +PLAYWRIGHT_CLI_SESSION=todo-app claude . +``` + +### Session Management + +```bash +playwright-cli session-list # List all sessions +playwright-cli session-stop [name] # Stop session (keeps profile) +playwright-cli session-stop-all # Stop all sessions +playwright-cli session-delete [name] # Delete session + profile data +``` + +## Headed Mode + +Show the browser window for debugging: + +```bash +playwright-cli open https://playwright.dev --headed +``` + +## Examples + +### Form Submission + +```bash +playwright-cli open https://example.com/form +playwright-cli snapshot + +playwright-cli fill e1 "user@example.com" +playwright-cli fill e2 "password123" +playwright-cli click e3 +playwright-cli snapshot +``` + +### Multi-Tab Workflow + +```bash +playwright-cli open https://example.com +playwright-cli tab-new https://example.com/other +playwright-cli tab-list +playwright-cli tab-select 0 +playwright-cli snapshot +``` + +### Debugging with DevTools + +```bash +playwright-cli open https://example.com +playwright-cli click e4 +playwright-cli fill e7 "test" +playwright-cli console +playwright-cli network +``` + +### Tracing for Debug + +```bash +playwright-cli open https://example.com +playwright-cli tracing-start +playwright-cli click e4 +playwright-cli fill e7 "test" +playwright-cli tracing-stop +# Opens trace viewer with recorded actions +``` + +### Todo App Demo + +```bash +playwright-cli open https://demo.playwright.dev/todomvc/ --headed +playwright-cli type "Buy groceries" +playwright-cli press Enter +playwright-cli type "Water flowers" +playwright-cli press Enter +playwright-cli check e21 +playwright-cli check e35 +playwright-cli screenshot +``` + +## Comparison with Other Tools + +| Feature | playwright-cli | agent-browser | Playwriter | Stagehand | +|---------|---------------|---------------|------------|-----------| +| **Maintainer** | Microsoft | Vercel | Community | Browserbase | +| **Interface** | CLI | CLI | MCP | SDK | +| **Ref syntax** | `e5` | `@e5` | aria-ref | Natural language | +| **Sessions** | `--session` | `--session` | Your browser | Per-instance | +| **Tracing** | Built-in | Via Playwright | Via CDP | Via Playwright | +| **Headless** | Default | Default | No (your browser) | Default | +| **Extensions** | No | No | Yes (yours) | Possible | +| **Cold start** | ~2s | ~3-5s (Rust) | ~1s (extension) | ~2s | + +### When to Use playwright-cli + +- **AI agent automation** - Snapshot + ref pattern for LLMs +- **CLI-first workflows** - Shell scripts, CI/CD pipelines +- **Multi-session automation** - Parallel browser instances +- **Microsoft ecosystem** - Official Playwright tooling + +### When to Use Other Tools + +- **agent-browser** - Faster cold starts (Rust binary), more CLI commands +- **Playwriter** - Need your existing browser sessions, extensions, passwords +- **Stagehand** - Natural language automation, self-healing selectors +- **Playwright direct** - Maximum speed, full API control, TypeScript projects + +## Resources + +- **GitHub**: https://github.com/microsoft/playwright-cli +- **Skill**: https://github.com/microsoft/playwright-cli/tree/main/skills/playwright-cli +- **License**: Apache-2.0 +- **Part of**: `@playwright/mcp` package diff --git a/README.md b/README.md index 98bbabb3d9..7d91a52370 100644 --- a/README.md +++ b/README.md @@ -729,9 +729,10 @@ These use direct API calls via curl, avoiding MCP server startup entirely: - [Context7](https://context7.com/) - Real-time documentation access for thousands of libraries - [Repomix](https://github.com/yamadashy/repomix) - Pack codebases into AI-friendly context -**Browser Automation** (7 tools + anti-detect stack, [benchmarked](#browser-automation)): +**Browser Automation** (8 tools + anti-detect stack, [benchmarked](#browser-automation)): - [Playwright](https://playwright.dev/) - Fastest engine (0.9s form fill), parallel contexts, extensions, proxy (auto-installed) +- [playwright-cli](https://github.com/microsoft/playwright-cli) - Microsoft official CLI for AI agents, `--session` isolation, built-in tracing - [dev-browser](https://github.com/nicholasgriffintn/dev-browser) - Persistent profile, stays logged in, ARIA snapshots, pairs with DevTools - [agent-browser](https://github.com/vercel-labs/agent-browser) - CLI/CI/CD, `--session` parallel, ref-based element targeting - [Crawl4AI](https://github.com/unclecode/crawl4ai) - Bulk extraction, `arun_many` parallel (1.7x), LLM-ready markdown @@ -831,43 +832,46 @@ These catch formatting and syntax issues during editing, reducing preflight/post ## **Browser Automation** -7 browser tools + anti-detect stack, benchmarked and integrated for AI-assisted web automation, dev testing, data extraction, and bot detection evasion. Agents automatically select the optimal tool based on task requirements. +8 browser tools + anti-detect stack, benchmarked and integrated for AI-assisted web automation, dev testing, data extraction, and bot detection evasion. Agents automatically select the optimal tool based on task requirements. ### Performance Benchmarks Tested on macOS ARM64, all headless, warm daemon: -| Test | Playwright | dev-browser | agent-browser | Crawl4AI | Playwriter | Stagehand | -|------|-----------|-------------|---------------|----------|------------|-----------| -| **Navigate + Screenshot** | **1.43s** | 1.39s | 1.90s | 2.78s | 2.95s | 7.72s | -| **Form Fill** (4 fields) | **0.90s** | 1.34s | 1.37s | N/A | 2.24s | 2.58s | -| **Data Extraction** (5 items) | 1.33s | **1.08s** | 1.53s | 2.53s | 2.68s | 3.48s | -| **Multi-step** (click + nav) | **1.49s** | 1.49s | 3.06s | N/A | 4.37s | 4.48s | -| **Parallel** (3 sessions) | **1.6s** | N/A | 2.0s | 3.0s | N/A | Slow | +| Test | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | Playwriter | Stagehand | +|------|-----------|----------------|-------------|---------------|----------|------------|-----------| +| **Navigate + Screenshot** | **1.43s** | ~1.9s | 1.39s | 1.90s | 2.78s | 2.95s | 7.72s | +| **Form Fill** (4 fields) | **0.90s** | ~1.4s | 1.34s | 1.37s | N/A | 2.24s | 2.58s | +| **Data Extraction** (5 items) | 1.33s | ~1.5s | **1.08s** | 1.53s | 2.53s | 2.68s | 3.48s | +| **Multi-step** (click + nav) | **1.49s** | ~2.0s | 1.49s | 3.06s | N/A | 4.37s | 4.48s | +| **Parallel** (3 sessions) | **1.6s** | ~2.0s | N/A | 2.0s | 3.0s | N/A | Slow | ### Feature Matrix -| Feature | Playwright | dev-browser | agent-browser | Crawl4AI | Playwriter | Stagehand | -|---------|-----------|-------------|---------------|----------|------------|-----------| -| **Headless** | Yes | Yes | Yes | Yes | No (your browser) | Yes | -| **Proxy/VPN** | Full | Via args | No | Full | Your browser | Via args | -| **Extensions** | Yes (persistent) | Yes (profile) | No | No | Yes (yours) | Possible | -| **Password managers** | Partial (needs unlock) | Partial | No | No | **Yes** (unlocked) | No | -| **Parallel sessions** | 5 ctx/2.1s | Shared | 3 sess/2.0s | arun_many 1.7x | Shared | Per-instance | -| **Session persistence** | storageState | Profile dir | state save/load | user_data_dir | Your browser | Per-instance | -| **Natural language** | No | No | No | LLM extraction | No | Yes | -| **Self-healing** | No | No | No | No | No | Yes | +| Feature | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | Playwriter | Stagehand | +|---------|-----------|----------------|-------------|---------------|----------|------------|-----------| +| **Headless** | Yes | Yes (default) | Yes | Yes | Yes | No (your browser) | Yes | +| **Proxy/VPN** | Full | No | Via args | No | Full | Your browser | Via args | +| **Extensions** | Yes (persistent) | No | Yes (profile) | No | No | Yes (yours) | Possible | +| **Password managers** | Partial (needs unlock) | No | Partial | No | No | **Yes** (unlocked) | No | +| **Parallel sessions** | 5 ctx/2.1s | --session | Shared | 3 sess/2.0s | arun_many 1.7x | Shared | Per-instance | +| **Session persistence** | storageState | Profile dir | Profile dir | state save/load | user_data_dir | Your browser | Per-instance | +| **Tracing** | Full API | Built-in CLI | Via Playwright | Via Playwright | No | Via CDP | Via Playwright | +| **Natural language** | No | No | No | No | LLM extraction | No | Yes | +| **Self-healing** | No | No | No | No | No | No | Yes | +| **Maintainer** | Microsoft | Microsoft | Community | Vercel | Community | Community | Browserbase | ### Tool Selection | Need | Tool | Why | |------|------|-----| | **Fastest automation** | Playwright | 0.9s form fill, parallel contexts | +| **AI agent (CLI)** | playwright-cli | Microsoft official, `--session` isolation, built-in tracing | | **Stay logged in** | dev-browser | Profile persists across restarts | | **Your extensions/passwords** | Playwriter | Already unlocked in your browser | | **Bulk extraction** | Crawl4AI | Purpose-built, parallel, LLM-ready output | | **Self-hosted crawling** | WaterCrawl | Docker deployment, web search, sitemap generation | -| **CLI/CI/CD** | agent-browser | No server needed, `--session` isolation | +| **CLI/CI/CD** | playwright-cli or agent-browser | No server needed, `--session` isolation | | **Unknown pages** | Stagehand | Natural language, self-healing | | **Performance debugging** | Chrome DevTools MCP | Companion tool, pairs with any browser | | **Bot detection evasion** | Anti-detect stack | Camoufox (full) or rebrowser-patches (quick) | From 4bc251f1f1a4d4714a78c5ca14b9ceb089a7d716 Mon Sep 17 00:00:00 2001 From: marcusquinn <6428977+marcusquinn@users.noreply.github.com> Date: Sun, 25 Jan 2026 03:05:29 +0000 Subject: [PATCH 2/2] fix: address review feedback on playwright-cli docs - Fix cold start comparison (playwright-cli ~2s is faster than agent-browser ~3-5s) - Add snapshot command to Todo App Demo for clarity - Use credential placeholder instead of hardcoded password - Fix README headless column consistency for agent-browser --- .agent/tools/browser/playwright-cli.md | 11 ++++++----- README.md | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/.agent/tools/browser/playwright-cli.md b/.agent/tools/browser/playwright-cli.md index faafd64abb..b8c9d3c29c 100644 --- a/.agent/tools/browser/playwright-cli.md +++ b/.agent/tools/browser/playwright-cli.md @@ -47,7 +47,7 @@ playwright-cli close **Performance**: Similar to agent-browser (both use Playwright engine). Navigate+screenshot ~1.9s, form fill ~1.4s. -**vs agent-browser**: playwright-cli uses simpler ref syntax (`e5` vs `@e5`), has built-in tracing, and is Microsoft-maintained. agent-browser has Rust CLI for faster cold starts. +**vs agent-browser**: playwright-cli uses simpler ref syntax (`e5` vs `@e5`), has built-in tracing, and is Microsoft-maintained. agent-browser has more CLI commands and a Rust binary (but slower cold start ~3-5s vs ~2s). **vs Playwriter MCP**: playwright-cli runs headless with isolated sessions. Playwriter uses your existing browser (headed, with your extensions/passwords). @@ -260,7 +260,7 @@ playwright-cli open https://example.com/form playwright-cli snapshot playwright-cli fill e1 "user@example.com" -playwright-cli fill e2 "password123" +playwright-cli fill e2 "$PASSWORD" # Store credentials in env var or secure vault playwright-cli click e3 playwright-cli snapshot ``` @@ -304,8 +304,9 @@ playwright-cli type "Buy groceries" playwright-cli press Enter playwright-cli type "Water flowers" playwright-cli press Enter -playwright-cli check e21 -playwright-cli check e35 +playwright-cli snapshot # Get refs for the todo items +playwright-cli check e21 # Check first todo (ref from snapshot) +playwright-cli check e35 # Check second todo (ref from snapshot) playwright-cli screenshot ``` @@ -331,7 +332,7 @@ playwright-cli screenshot ### When to Use Other Tools -- **agent-browser** - Faster cold starts (Rust binary), more CLI commands +- **agent-browser** - More CLI commands, Rust binary (but slower cold start) - **Playwriter** - Need your existing browser sessions, extensions, passwords - **Stagehand** - Natural language automation, self-healing selectors - **Playwright direct** - Maximum speed, full API control, TypeScript projects diff --git a/README.md b/README.md index 7d91a52370..14a3839b17 100644 --- a/README.md +++ b/README.md @@ -850,7 +850,7 @@ Tested on macOS ARM64, all headless, warm daemon: | Feature | Playwright | playwright-cli | dev-browser | agent-browser | Crawl4AI | Playwriter | Stagehand | |---------|-----------|----------------|-------------|---------------|----------|------------|-----------| -| **Headless** | Yes | Yes (default) | Yes | Yes | Yes | No (your browser) | Yes | +| **Headless** | Yes | Yes (default) | Yes | Yes (default) | Yes | No (your browser) | Yes | | **Proxy/VPN** | Full | No | Via args | No | Full | Your browser | Via args | | **Extensions** | Yes (persistent) | No | Yes (profile) | No | No | Yes (yours) | Possible | | **Password managers** | Partial (needs unlock) | No | Partial | No | No | **Yes** (unlocked) | No |