You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Replacing the MCP Playwright server with @playwright/cli is well-motivated: the CLI (released early 2026) cuts token usage by ~4x by saving snapshots to disk rather than streaming them into context. The migration requires changes across the gh-aw workflow engine — primarily replacing Docker MCP container config generation with a bash-based setup that installs and invokes playwright-cli commands. The existing tools: playwright: frontmatter key can be preserved as the user-facing API; only the internal rendering changes.
The CLI approach is specifically designed for coding agents (Claude Code, Copilot, Cursor) with filesystem and shell access — exactly the environment gh-aw workflows run in.
Current MCP Architecture in gh-aw
The existing implementation has these key pieces:
pkg/workflow/mcp_config_playwright_renderer.go — Renders the MCP Gateway JSON config for the Playwright Docker container (mcr.microsoft.com/playwright/mcp), with Docker args --init --network host --security-opt seccomp=unconfined --ipc=host and entrypoint args --output-dir /tmp/gh-aw/mcp-logs/playwright --no-sandbox
pkg/workflow/mcp_setup_generator.go — Includes Playwright in setup sequence
Playwright CLI Command Set
# Install
npm install -g `@playwright/cli`
playwright-cli install --skills # installs SKILL.md into agent context# Core commands agents use
playwright-cli open (url) # open browser + navigate
playwright-cli snapshot # → saves YAML to .playwright-cli/, returns filepath
playwright-cli click (ref) # click element by ref ID from snapshot
playwright-cli fill (ref) (value) # fill input
playwright-cli screenshot # → saves PNG to .playwright-cli/
playwright-cli close # close session
All output artifacts (snapshots, screenshots) land in .playwright-cli/ on disk.
Migration Approach
The user-facing tools: playwright: frontmatter key can remain unchanged. Internally, the rendering changes from "configure a Docker MCP container" to "install CLI + inject skill knowledge + grant bash access."
Two viable strategies:
Option A — Implicit bash integration (simpler)
When tools: playwright: is set, gh-aw auto-installs @playwright/cli in the setup step (like npm install -g @playwright/cli && npx playwright install chromium)
Runs playwright-cli install --skills to drop SKILL.md into agent context
Grants bash: ["playwright-cli *"] automatically
No MCP server in the generated config at all
Option B — New playwright-cli tool key (explicit)
Introduce tools: playwright-cli: as a distinct config key
Keep tools: playwright: as legacy (deprecated) pointing to MCP
Enables gradual migration and A/B testing
Recommended: Option A — transparent to workflow authors, simpler migration path.
Files to Change (Estimated Scope)
File
Change
pkg/workflow/mcp_config_playwright_renderer.go
Delete or repurpose — no longer generates Docker MCP config
pkg/workflow/playwright_tools.go
Remove MCP tool list (no longer needed for CLI)
pkg/workflow/mcp_playwright_config.go
Keep expression extractor (still needed for args passthrough to CLI)
pkg/workflow/tools_types.go
Keep PlaywrightToolConfig; possibly add Browser field
pkg/workflow/mcp_renderer.go
Remove "playwright" case (CLI is not an MCP server)
No Docker required — CLI runs directly on the runner; removes the Docker socket dependency for playwright specifically
--no-sandbox still needed — Chromium still needs --no-sandbox on GitHub Actions runners; this becomes a CLI flag: playwright-cli open --no-sandbox (url)
Output directory — Snapshots/screenshots go to .playwright-cli/ by default (configurable); gh-aw could redirect to /tmp/gh-aw/playwright-cli/ via env var or session flag
args field passthrough — Current PlaywrightToolConfig.Args could map to CLI flags (e.g., --browser chromium)
Skill injection — playwright-cli install --skills creates a SKILL.md that must be injected into the agent's system prompt (similar to the existing playwright_prompt.md)
Network firewall — Network domain restrictions still apply; CLI uses the same Chromium and respects the workflow's network: allowed: list
Recommendations
Adopt Option A (transparent swap): keep tools: playwright: frontmatter unchanged; replace the Docker MCP container with CLI setup under the hood
Preserve the args field: map existing args: ["--browser", "chromium"] to CLI flags
Run playwright-cli install --skills in the setup step and inject the resulting SKILL.md into the agent prompt
Redirect output to /tmp/gh-aw/playwright-cli/ to keep artifacts in the existing log path convention
Update integration tests: replace MCP tool name assertions with CLI bash command patterns
Deprecate version field: the MCP Docker image used a single image (no version); CLI follows npm semver — consider adding version support to pin @playwright/cli@x.y.z
Activity
github-actions commentedon Mar 18, 2026
🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️
github-actions commentedon Mar 18, 2026
🔍 Scout Research Report
Triggered by @pelikhan
Executive Summary
Replacing the MCP Playwright server with
@playwright/cliis well-motivated: the CLI (released early 2026) cuts token usage by ~4x by saving snapshots to disk rather than streaming them into context. The migration requires changes across the gh-aw workflow engine — primarily replacing Docker MCP container config generation with a bash-based setup that installs and invokesplaywright-clicommands. The existingtools: playwright:frontmatter key can be preserved as the user-facing API; only the internal rendering changes.Click to expand detailed findings
Research Findings
Why Replace MCP with CLI?
.playwright-cli/; not in contextmcr.microsoft.com/playwright/mcp)npm install -g@playwright/cli`` + browser installThe CLI approach is specifically designed for coding agents (Claude Code, Copilot, Cursor) with filesystem and shell access — exactly the environment gh-aw workflows run in.
Current MCP Architecture in gh-aw
The existing implementation has these key pieces:
pkg/workflow/mcp_config_playwright_renderer.go— Renders the MCP Gateway JSON config for the Playwright Docker container (mcr.microsoft.com/playwright/mcp), with Docker args--init --network host --security-opt seccomp=unconfined --ipc=hostand entrypoint args--output-dir /tmp/gh-aw/mcp-logs/playwright --no-sandboxpkg/workflow/playwright_tools.go— Defines the 20 MCP tool names allowed (browser_click,browser_navigate,browser_snapshot,browser_take_screenshot, etc.)pkg/workflow/mcp_playwright_config.go—PlaywrightToolConfigstruct (Version,Args) and expression-extraction helpers for secure arg handlingpkg/workflow/tools_types.go—ToolsConfig.Playwright *PlaywrightToolConfigfieldpkg/workflow/mcp_renderer.go— Routes"playwright"key toRenderPlaywrightrendererpkg/workflow/mcp_renderer_builtin.go—renderPlaywrightTOMLfor Codex enginepkg/workflow/codex_engine.go— Codex-specific playwright configpkg/workflow/mcp_setup_generator.go— Includes Playwright in setup sequencePlaywright CLI Command Set
All output artifacts (snapshots, screenshots) land in
.playwright-cli/on disk.Migration Approach
The user-facing
tools: playwright:frontmatter key can remain unchanged. Internally, the rendering changes from "configure a Docker MCP container" to "install CLI + inject skill knowledge + grant bash access."Two viable strategies:
Option A — Implicit bash integration (simpler)
tools: playwright:is set, gh-aw auto-installs@playwright/cliin the setup step (likenpm install -g@playwright/cli&& npx playwright install chromium)playwright-cli install --skillsto drop SKILL.md into agent contextbash: ["playwright-cli *"]automaticallyOption B — New
playwright-clitool key (explicit)tools: playwright-cli:as a distinct config keytools: playwright:as legacy (deprecated) pointing to MCPRecommended: Option A — transparent to workflow authors, simpler migration path.
Files to Change (Estimated Scope)
pkg/workflow/mcp_config_playwright_renderer.gopkg/workflow/playwright_tools.gopkg/workflow/mcp_playwright_config.goargspassthrough to CLI)pkg/workflow/tools_types.goPlaywrightToolConfig; possibly addBrowserfieldpkg/workflow/mcp_renderer.go"playwright"case (CLI is not an MCP server)pkg/workflow/mcp_renderer_builtin.gorenderPlaywrightTOMLpkg/workflow/mcp_setup_generator.gopkg/workflow/codex_engine.goactions/setup/md/playwright_prompt.mddocs/src/content/docs/reference/playwright.mdpkg/cli/workflows/test-playwright-args.mdpkg/workflow/playwright_mcp_integration_test.gopkg/cli/mcp_inspect_playwright_integration_test.goKey Technical Considerations
--no-sandboxstill needed — Chromium still needs--no-sandboxon GitHub Actions runners; this becomes a CLI flag:playwright-cli open --no-sandbox (url).playwright-cli/by default (configurable); gh-aw could redirect to/tmp/gh-aw/playwright-cli/via env var or session flagargsfield passthrough — CurrentPlaywrightToolConfig.Argscould map to CLI flags (e.g.,--browser chromium)playwright-cli install --skillscreates aSKILL.mdthat must be injected into the agent's system prompt (similar to the existingplaywright_prompt.md)network: allowed:listRecommendations
tools: playwright:frontmatter unchanged; replace the Docker MCP container with CLI setup under the hoodargsfield: map existingargs: ["--browser", "chromium"]to CLI flagsplaywright-cli install --skillsin the setup step and inject the resulting SKILL.md into the agent prompt/tmp/gh-aw/playwright-cli/to keep artifacts in the existing log path conventionversionfield: the MCP Docker image used a single image (no version); CLI follows npm semver — consider addingversionsupport to pin@playwright/cli@x.y.zKey Sources
@playwright/clinpm package]((www.npmjs.com/redacted)Suggested Next Steps
playwright-cliinstall tomcp_setup_generator.gosetup stepplaywright_prompt.mdwith CLI-specific output path and usage notestest-playwright-args.mdworkflow against the new implementation to validateReferences:
pelikhan commentedon Mar 18, 2026
@copilot option A
pelikhan commentedon Mar 18, 2026
@copilot update playwright to use cli by default, add tools.playwright.mode: cli | mcp to choose modes.
pelikhan commentedon Mar 18, 2026
@copilot add a mode "cli" | "mcp" to select the current MCP approach or using https://github.com/microsoft/playwright-cli directly.