feat: Replace Playwright MCP with agent-browser CLI

- Remove Playwright MCP server from plugin - Add new agent-browser skill for CLI-based browser automation - Rename /playwright-test to /test-browser command - Update all commands and agents to use agent-browser CLI - Update README and plugin.json agent-browser is Vercel's headless browser CLI designed for AI agents. It uses ref-based selection (@e1, @e2) from accessibility snapshots and provides a simpler CLI interface compared to MCP tools. Key benefits: - No MCP server required - Simpler Bash-based workflow - Same ref-based element selection - Better for quick automation tasks 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-14 15:56:59 -08:00
parent 012a638d31
commit 31bd85f60b
11 changed files with 398 additions and 152 deletions
--- a/plugins/compound-engineering/commands/feature-video.md
+++ b/plugins/compound-engineering/commands/feature-video.md
@@ -13,7 +13,7 @@ argument-hint: "[PR number or 'current'] [optional: base URL, default localhost:
 <role>Developer Relations Engineer creating feature demo videos</role>

 This command creates professional video walkthroughs of features for PR documentation:
- Records browser interactions using Playwright video capture
+- Records browser interactions using agent-browser CLI
 - Demonstrates the complete user flow
 - Uploads the video for easy sharing
 - Updates the PR description with an embedded video
@@ -22,12 +22,26 @@ This command creates professional video walkthroughs of features for PR document

 <requirements>
 - Local development server running (e.g., `bin/dev`, `rails server`)
- Playwright MCP server connected
+- agent-browser CLI installed
 - Git repository with a PR to document
 - `ffmpeg` installed (for video conversion)
 - `rclone` configured (optional, for cloud upload - see rclone skill)
 </requirements>

+## Setup
+
+**Check installation:**
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
+```
+
+**Install if needed:**
+```bash
+npm install -g agent-browser && agent-browser install
+```
+
+See the `agent-browser` skill for detailed usage.
+
 ## Main Tasks

 ### 1. Parse Arguments
@@ -118,26 +132,9 @@ Does this look right?
 mkdir -p tmp/videos
 ```

-**Start browser with video recording using Playwright MCP:**
+**Recording approach: Use browser screenshots as frames**

-Note: Playwright MCP's browser_navigate will be used, and we'll use browser_run_code to enable video recording:
-
-```javascript
-// Enable video recording context
-mcp__plugin_compound-engineering_pw__browser_run_code({
-  code: `async (page) => {
-    // Video recording is enabled at context level
-    // The MCP server handles this automatically
-    return 'Video recording active';
-  }`
-})
-```
-
-**Alternative: Use browser screenshots as frames**
-
-If video recording isn't available via MCP, fall back to:
-1. Take screenshots at key moments
-2. Combine into a GIF using ffmpeg
+agent-browser captures screenshots at key moments, then combine into video using ffmpeg:

 ```bash
 ffmpeg -framerate 2 -pattern_type glob -i 'tmp/screenshots/*.png' -vf "scale=1280:-1" tmp/videos/feature-demo.gif
@@ -152,32 +149,32 @@ ffmpeg -framerate 2 -pattern_type glob -i 'tmp/screenshots/*.png' -vf "scale=128
 Execute the planned flow, capturing each step:

 **Step 1: Navigate to starting point**
-```
-mcp__plugin_compound-engineering_pw__browser_navigate({ url: "[base-url]/[start-route]" })
-mcp__plugin_compound-engineering_pw__browser_wait_for({ time: 2 })
-mcp__plugin_compound-engineering_pw__browser_take_screenshot({ filename: "tmp/screenshots/01-start.png" })
+```bash
+agent-browser open "[base-url]/[start-route]"
+agent-browser wait 2000
+agent-browser screenshot tmp/screenshots/01-start.png
 ```

 **Step 2: Perform navigation/interactions**
-```
-mcp__plugin_compound-engineering_pw__browser_click({ element: "[description]", ref: "[ref]" })
-mcp__plugin_compound-engineering_pw__browser_wait_for({ time: 1 })
-mcp__plugin_compound-engineering_pw__browser_take_screenshot({ filename: "tmp/screenshots/02-navigate.png" })
+```bash
+agent-browser snapshot -i  # Get refs
+agent-browser click @e1    # Click navigation element
+agent-browser wait 1000
+agent-browser screenshot tmp/screenshots/02-navigate.png
 ```

 **Step 3: Demonstrate feature**
-```
-mcp__plugin_compound-engineering_pw__browser_snapshot({})
-// Identify interactive elements
-mcp__plugin_compound-engineering_pw__browser_click({ element: "[feature element]", ref: "[ref]" })
-mcp__plugin_compound-engineering_pw__browser_wait_for({ time: 1 })
-mcp__plugin_compound-engineering_pw__browser_take_screenshot({ filename: "tmp/screenshots/03-feature.png" })
+```bash
+agent-browser snapshot -i  # Get refs for feature elements
+agent-browser click @e2    # Click feature element
+agent-browser wait 1000
+agent-browser screenshot tmp/screenshots/03-feature.png
 ```

 **Step 4: Capture result**
-```
-mcp__plugin_compound-engineering_pw__browser_wait_for({ time: 2 })
-mcp__plugin_compound-engineering_pw__browser_take_screenshot({ filename: "tmp/screenshots/04-result.png" })
+```bash
+agent-browser wait 2000
+agent-browser screenshot tmp/screenshots/04-result.png
 ```

 **Create video/GIF from screenshots:**
@@ -189,17 +186,14 @@ mkdir -p tmp/videos tmp/screenshots
 # Create MP4 video (RECOMMENDED - better quality, smaller size)
 # -framerate 0.5 = 2 seconds per frame (slower playback)
 # -framerate 1 = 1 second per frame
-ffmpeg -y -framerate 0.5 -pattern_type glob -i '.playwright-mcp/tmp/screenshots/*.png' \
+ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
  -c:v libx264 -pix_fmt yuv420p -vf "scale=1280:-2" \
  tmp/videos/feature-demo.mp4

 # Create low-quality GIF for preview (small file, for GitHub embed)
-ffmpeg -y -framerate 0.5 -pattern_type glob -i '.playwright-mcp/tmp/screenshots/*.png' \
+ffmpeg -y -framerate 0.5 -pattern_type glob -i 'tmp/screenshots/*.png' \
  -vf "scale=640:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse" \
  -loop 0 tmp/videos/feature-demo-preview.gif
-
-# Copy screenshots to project folder for easy access
-cp -r .playwright-mcp/tmp/screenshots tmp/
 ```

 **Note:**
--- a/plugins/compound-engineering/commands/playwright-test.md
+++ b/plugins/compound-engineering/commands/playwright-test.md
@@ -1,12 +1,12 @@
 ---
-name: playwright-test
-description: Run Playwright browser tests on pages affected by current PR or branch
+name: test-browser
+description: Run browser tests on pages affected by current PR or branch
 argument-hint: "[PR number, branch name, or 'current' for current branch]"
 ---

-# Playwright Test Command
+# Browser Test Command

-<command_purpose>Run end-to-end browser tests on pages affected by a PR or branch changes using Playwright MCP.</command_purpose>
+<command_purpose>Run end-to-end browser tests on pages affected by a PR or branch changes using agent-browser CLI.</command_purpose>

 ## Introduction

@@ -22,10 +22,25 @@ This command tests affected pages in a real browser, catching issues that unit t

 <requirements>
 - Local development server running (e.g., `bin/dev`, `rails server`)
- Playwright MCP server connected
+- agent-browser CLI installed
 - Git repository with changes to test
 </requirements>

+## Setup
+
+**Check installation:**
+```bash
+command -v agent-browser >/dev/null 2>&1 && echo "Installed" || echo "NOT INSTALLED"
+```
+
+**Install if needed:**
+```bash
+npm install -g agent-browser
+agent-browser install  # Downloads Chromium
+```
+
+See the `agent-browser` skill for detailed usage.
+
 ## Main Tasks

 ### 1. Determine Test Scope
@@ -77,9 +92,9 @@ Build a list of URLs to test based on the mapping.

 Before testing, verify the local server is accessible:

-```
-mcp__playwright__browser_navigate({ url: "http://localhost:3000" })
-mcp__playwright__browser_snapshot({})
+```bash
+agent-browser open http://localhost:3000
+agent-browser snapshot -i
 ```

 If server is not running, inform user:
@@ -90,7 +105,7 @@ Please start your development server:
 - Rails: `bin/dev` or `rails server`
 - Node: `npm run dev`

-Then run `/playwright-test` again.
+Then run `/test-browser` again.
 ```

 </check_server>
@@ -102,26 +117,27 @@ Then run `/playwright-test` again.
 For each affected route:

 **Step 1: Navigate and capture snapshot**
-```
-mcp__playwright__browser_navigate({ url: "http://localhost:3000/[route]" })
-mcp__playwright__browser_snapshot({})
+```bash
+agent-browser open "http://localhost:3000/[route]"
+agent-browser snapshot -i
 ```

-**Step 2: Check for errors**
-```
-mcp__playwright__browser_console_messages({ level: "error" })
+**Step 2: Check for errors** (use headed mode for console inspection)
+```bash
+agent-browser --headed open "http://localhost:3000/[route]"
 ```

 **Step 3: Verify key elements**
+- Use `agent-browser snapshot -i` to get interactive elements with refs
 - Page title/heading present
 - Primary content rendered
 - No error messages visible
 - Forms have expected fields

-**Step 4: Test critical interactions (if applicable)**
-```
-mcp__playwright__browser_click({ element: "[description]", ref: "[ref]" })
-mcp__playwright__browser_snapshot({})
+**Step 4: Test critical interactions**
+```bash
+agent-browser click @e1  # Use ref from snapshot
+agent-browser snapshot -i
 ```

 </test_pages>
@@ -162,8 +178,7 @@ Did it work correctly?
 When a test fails:

 1. **Document the failure:**
-   - Screenshot the error state
-   - Capture console errors
+   - Screenshot the error state: `agent-browser screenshot error.png`
   - Note the exact reproduction steps

 2. **Ask user how to proceed:**
@@ -186,7 +201,7 @@ When a test fails:
   - Re-run the failing test

 4. **If "Create todo":**
-   - Create `{id}-pending-p1-playwright-{description}.md`
+   - Create `{id}-pending-p1-browser-test-{description}.md`
   - Continue testing

 5. **If "Skip":**
@@ -202,7 +217,7 @@ When a test fails:
 After all tests complete, present summary:

 ```markdown
-## 🎭 Playwright Test Results
+## Browser Test Results

 **Test Scope:** PR #[number] / [branch name]
 **Server:** http://localhost:3000
@@ -211,23 +226,23 @@ After all tests complete, present summary:

 | Route | Status | Notes |
 |-------|--------|-------|
-| `/users` | ✅ Pass | |
-| `/settings` | ✅ Pass | |
-| `/dashboard` | ❌ Fail | Console error: [msg] |
-| `/checkout` | ⏭️ Skip | Requires payment credentials |
+| `/users` | Pass | |
+| `/settings` | Pass | |
+| `/dashboard` | Fail | Console error: [msg] |
+| `/checkout` | Skip | Requires payment credentials |

 ### Console Errors: [count]
 - [List any errors found]

 ### Human Verifications: [count]
- OAuth flow: ✅ Confirmed
- Email delivery: ✅ Confirmed
+- OAuth flow: Confirmed
+- Email delivery: Confirmed

 ### Failures: [count]
 - `/dashboard` - [issue description]

 ### Created Todos: [count]
- `005-pending-p1-playwright-dashboard-error.md`
+- `005-pending-p1-browser-test-dashboard-error.md`

 ### Result: [PASS / FAIL / PARTIAL]
 ```
@@ -238,11 +253,22 @@ After all tests complete, present summary:

 ```bash
 # Test current branch changes
-/playwright-test
+/test-browser

 # Test specific PR
-/playwright-test 847
+/test-browser 847

 # Test specific branch
-/playwright-test feature/new-dashboard
+/test-browser feature/new-dashboard
+```
+
+## Key agent-browser Commands
+
+```bash
+agent-browser open <url>           # Navigate
+agent-browser snapshot -i          # Interactive elements with refs
+agent-browser click @e1            # Click by ref
+agent-browser fill @e1 "text"      # Fill input
+agent-browser screenshot out.png   # Screenshot
+agent-browser --headed open <url>  # Visible browser
 ```
--- a/plugins/compound-engineering/commands/workflows/review.md
+++ b/plugins/compound-engineering/commands/workflows/review.md
@@ -445,8 +445,8 @@ After presenting the Summary Report, offer appropriate testing based on project

 **For Web Projects:**
 ```markdown
-**"Want to run Playwright browser tests on the affected pages?"**
-1. Yes - run `/playwright-test`
+**"Want to run browser tests on the affected pages?"**
+1. Yes - run `/test-browser`
 2. No - skip
 ```

@@ -460,7 +460,7 @@ After presenting the Summary Report, offer appropriate testing based on project
 **For Hybrid Projects (e.g., Rails + Hotwire Native):**
 ```markdown
 **"Want to run end-to-end tests?"**
-1. Web only - run `/playwright-test`
+1. Web only - run `/test-browser`
 2. iOS only - run `/xcode-test`
 3. Both - run both commands
 4. No - skip
@@ -470,22 +470,22 @@ After presenting the Summary Report, offer appropriate testing based on project

 #### If User Accepts Web Testing:

-Spawn a subagent to run Playwright tests (preserves main context):
+Spawn a subagent to run browser tests (preserves main context):

 ```
-Task general-purpose("Run /playwright-test for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
+Task general-purpose("Run /test-browser for PR #[number]. Test all affected pages, check for console errors, handle failures by creating todos and fixing.")
 ```

 The subagent will:
 1. Identify pages affected by the PR
-2. Navigate to each page and capture snapshots
+2. Navigate to each page and capture snapshots (using Playwright MCP or agent-browser CLI)
 3. Check for console errors
 4. Test critical interactions
 5. Pause for human verification on OAuth/email/payment flows
 6. Create P1 todos for any failures
 7. Fix and retry until all tests pass

-**Standalone:** `/playwright-test [PR number]`
+**Standalone:** `/test-browser [PR number]`

 #### If User Accepts iOS Testing:

--- a/plugins/compound-engineering/commands/workflows/work.md
+++ b/plugins/compound-engineering/commands/workflows/work.md
@@ -181,11 +181,13 @@ This command takes a work document (plan, specification, or todo file) and execu
   bin/dev  # Run in background
   ```

-   **Step 2: Capture screenshots with Playwright MCP tools**
-   - `browser_navigate` to go to affected pages
-   - `browser_resize` to set viewport (desktop or mobile as needed)
-   - `browser_snapshot` to verify page state
-   - `browser_take_screenshot` to capture images
+   **Step 2: Capture screenshots with agent-browser CLI**
+   ```bash
+   agent-browser open http://localhost:3000/[route]
+   agent-browser snapshot -i
+   agent-browser screenshot output.png
+   ```
+   See the `agent-browser` skill for detailed usage.

   **Step 3: Upload using imgup skill**
   ```bash