feat(browser): add playwright-cli subagent for AI agent automation#196
feat(browser): add playwright-cli subagent for AI agent automation#196marcusquinn merged 2 commits intomainfrom
Conversation
- 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.
Summary of ChangesHello @marcusquinn, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the repository's capabilities for AI agent browser automation by integrating Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Warning Rate limit exceeded
⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. WalkthroughThe PR introduces playwright-cli as a new browser automation tool for AI agents. It updates documentation to emphasize CLI-first workflows, integrating the tool into feature matrices, decision trees, and quick references with support for session isolation and built-in tracing. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces playwright-cli as a new browser automation tool, which is a great addition for AI agent workflows. The documentation is comprehensive, with a new dedicated file for playwright-cli and updates to the existing browser automation decision tree and README. The changes are well-structured and clearly explain the purpose and usage of the new tool. I've found a few minor inconsistencies in the documentation that could be addressed to improve clarity. Overall, this is a solid contribution.
| **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 | ||
|
|
||
| <!-- AI-CONTEXT-END --> | ||
|
|
||
| ## 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 <url> # Navigate to URL | ||
| playwright-cli close # Close the page | ||
| playwright-cli type <text> # Type text into focused/editable element | ||
| playwright-cli click <ref> [button] # Click element (left/right/middle) | ||
| playwright-cli dblclick <ref> [button] # Double-click element | ||
| playwright-cli fill <ref> <text> # Clear and fill input | ||
| playwright-cli drag <startRef> <endRef> # Drag and drop between elements | ||
| playwright-cli hover <ref> # Hover over element | ||
| playwright-cli select <ref> <value> # Select dropdown option | ||
| playwright-cli upload <file> # Upload file(s) | ||
| playwright-cli check <ref> # Check checkbox/radio | ||
| playwright-cli uncheck <ref> # Uncheck checkbox | ||
| playwright-cli snapshot # Get accessibility tree with refs | ||
| playwright-cli eval <func> [ref] # Evaluate JavaScript | ||
| playwright-cli dialog-accept [prompt] # Accept dialog (with optional prompt text) | ||
| playwright-cli dialog-dismiss # Dismiss dialog | ||
| playwright-cli resize <width> <height> # 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 <key> # Press key (Enter, ArrowDown, Tab, etc.) | ||
| playwright-cli keydown <key> # Press key down | ||
| playwright-cli keyup <key> # Release key | ||
| ``` | ||
|
|
||
| ### Mouse | ||
|
|
||
| ```bash | ||
| playwright-cli mousemove <x> <y> # Move mouse to position | ||
| playwright-cli mousedown [button] # Press mouse button | ||
| playwright-cli mouseup [button] # Release mouse button | ||
| playwright-cli mousewheel <dx> <dy> # Scroll mouse wheel | ||
| ``` | ||
|
|
||
| ### Save As | ||
|
|
||
| ```bash | ||
| playwright-cli screenshot # Screenshot current page | ||
| playwright-cli screenshot <ref> # 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 <index> # Switch to tab | ||
| ``` | ||
|
|
||
| ### DevTools | ||
|
|
||
| ```bash | ||
| playwright-cli console [min-level] # List console messages | ||
| playwright-cli network # List network requests | ||
| playwright-cli run-code <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 <url> # 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 | |
There was a problem hiding this comment.
There appears to be a contradiction regarding the cold start performance comparison between playwright-cli and agent-browser.
- On line 50, the text says:
agent-browser has Rust CLI for faster cold starts. - However, the comparison table on line 323 shows
playwright-clias being faster (~2s) thanagent-browser(~3-5s (Rust)).
Please review and correct this for consistency.
| playwright-cli check e21 | ||
| playwright-cli check e35 |
There was a problem hiding this comment.
The Todo App Demo uses element references (e21, e35) without showing how they are obtained. To make the example clearer and self-contained, a playwright-cli snapshot command should be added before the check commands to demonstrate the standard workflow of getting references before using them. For example:
...
playwright-cli type "Water flowers"
playwright-cli press Enter
playwright-cli snapshot # Get refs for the todo items
playwright-cli check e21
playwright-cli check e35
...
README.md
Outdated
| | **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 | |
There was a problem hiding this comment.
There's a small inconsistency in the Feature Matrix. For agent-browser, the Headless feature is listed as Yes. However, in .agent/tools/browser/browser-automation.md, it's specified as Yes (default). To maintain consistency across documentation files, this should be updated.
| | **Headless** | Yes | Yes (default) | Yes | Yes | Yes | No (your browser) | Yes | | |
| | **Headless** | Yes | Yes (default) | Yes | Yes (default) | Yes | No (your browser) | Yes | |
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sun Jan 25 03:02:35 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
🤖 Augment PR SummarySummary: This PR adds first-class documentation for Microsoft’s Changes:
Technical Notes: Highlights 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| | **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 | |
There was a problem hiding this comment.
The comparison section is internally inconsistent about agent-browser startup time: it says agent-browser has "faster cold starts", but the table lists agent-browser cold start as ~3-5s (slower than ~2s for playwright-cli). Consider reconciling these so readers don’t get conflicting guidance.
Other Locations
.agent/tools/browser/playwright-cli.md:50.agent/tools/browser/playwright-cli.md:334
🤖 Was this useful? React with 👍 or 👎
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In @.agent/tools/browser/playwright-cli.md:
- Around line 258-266: Replace the hardcoded password in the example Playwright
CLI snippet by using a credential placeholder (e.g., "$PASSWORD") and update the
surrounding Markdown to include a brief note instructing users to store
credentials securely (environment variable or secret vault); locate the snippet
containing the commands (playwright-cli fill e2 "password123") and change that
invocation to use the placeholder, and add one-line guidance about secure
credential storage adjacent to the snippet.
- 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
|
🔍 Code Quality Report�[0;35m[MONITOR]�[0m Code Review Monitoring Report �[0;34m[INFO]�[0m Latest Quality Status: �[0;34m[INFO]�[0m Recent monitoring activity: 📈 Current Quality Metrics
Generated on: Sun Jan 25 03:07:24 UTC 2026 Generated by AI DevOps Framework Code Review Monitoring |
1 participant
Summary
playwright-cli.mdsubagent with Microsoft official CLI documentationbrowser-automation.mddecision tree to include playwright-cliREADME.mdwith playwright-cli in browser tools section (now 8 tools + anti-detect stack)What is playwright-cli?
playwright-cli is Microsoft's official CLI for AI agents, part of
@playwright/mcp. It provides:e1,e2,e3)--sessionflag for parallel browser instances with persistent profilestracing-start/stopfor debuggingWhen to use playwright-cli vs other tools
Installation
Related
Summary by CodeRabbit
✏️ Tip: You can customize this high-level summary in your review settings.