{"_id":"playwright-mcp-wsl","name":"playwright-mcp-wsl","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"playwright-mcp-wsl","version":"1.0.0","description":"Drop-in WSL-safe wrapper for @playwright/mcp. Prevents GPU crashes on Windows Subsystem for Linux by disabling Chromium GPU acceleration through the dxg bridge.","repository":{"type":"git","url":"git+https://github.com/NorthwoodsSentinel/playwright-mcp-wsl.git"},"keywords":["playwright","mcp","wsl","wsl2","claude-code","browser-automation","windows","gpu-fix"],"author":{"name":"Robert Chuvala","email":"rob@northwoodssentinel.com"},"license":"Apache-2.0","engines":{"node":">=18"},"bin":{"playwright-mcp-wsl":"cli.js"},"main":"index.js","exports":{"./package.json":"./package.json",".":{"types":"./index.d.ts","default":"./index.js"}},"dependencies":{"@playwright/mcp":">=0.0.60"},"_id":"playwright-mcp-wsl@1.0.0","gitHead":"09c4ed539c34022f01ef7a7e98547f85ffa326be","types":"./index.d.ts","bugs":{"url":"https://github.com/NorthwoodsSentinel/playwright-mcp-wsl/issues"},"homepage":"https://github.com/NorthwoodsSentinel/playwright-mcp-wsl#readme","_nodeVersion":"20.20.0","_npmVersion":"10.8.2","dist":{"integrity":"sha512-6/B3gw+ajVhXwXkJDXPkvjfPfN1m/lmjJpxU9DaslUwZ8PmZ3Rds1KrD0VEPGyLRg7/7ylm3bVxu5qTvtx8vBg==","shasum":"3532468bf573dcddefaaff7cabcb3d1cbd31e7f0","tarball":"https://registry.npmjs.org/playwright-mcp-wsl/-/playwright-mcp-wsl-1.0.0.tgz","fileCount":8,"unpackedSize":20672,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIFd/EGyjRcd/2H6LPLxq78HRQMpsrqGZZnI9F6VSVPiNAiEA/hHxH4Mz3XZMVLEo5HrtFN7+2EWYLAZ62mPrBkveu34="}]},"_npmUser":{"name":"northwoodssentinel","email":"labs@northwoodssentinel.com"},"directories":{},"maintainers":[{"name":"northwoodssentinel","email":"labs@northwoodssentinel.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/playwright-mcp-wsl_1.0.0_1774722046736_0.66869177876078"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-28T18:20:46.736Z","1.0.0":"2026-03-28T18:20:46.870Z","modified":"2026-03-28T18:20:47.455Z"},"maintainers":[{"name":"northwoodssentinel","email":"labs@northwoodssentinel.com"}],"description":"Drop-in WSL-safe wrapper for @playwright/mcp. Prevents GPU crashes on Windows Subsystem for Linux by disabling Chromium GPU acceleration through the dxg bridge.","homepage":"https://github.com/NorthwoodsSentinel/playwright-mcp-wsl#readme","keywords":["playwright","mcp","wsl","wsl2","claude-code","browser-automation","windows","gpu-fix"],"repository":{"type":"git","url":"git+https://github.com/NorthwoodsSentinel/playwright-mcp-wsl.git"},"author":{"name":"Robert Chuvala","email":"rob@northwoodssentinel.com"},"bugs":{"url":"https://github.com/NorthwoodsSentinel/playwright-mcp-wsl/issues"},"license":"Apache-2.0","readme":"# playwright-mcp-wsl\n\nDrop-in WSL-safe wrapper for `@playwright/mcp`. Prevents Chromium GPU crashes on Windows Subsystem for Linux.\n\n## The Problem\n\nRunning Claude Code (or any Playwright-based browser automation) on WSL2 with parallel browser sessions causes cascading crashes:\n\n1. Chromium tries to allocate GPU memory through WSL's `dxg` bridge\n2. Multiple browser instances exhaust GPU memory allocations\n3. Chrome processes SEGFAULT (signal 11)\n4. Crash cascade takes down the entire WSL instance\n\nThis is invisible to users — WSL just \"crashes\" or \"freezes\" with no clear error.\n\n## The Fix\n\nThis package wraps `@playwright/mcp` and automatically injects GPU-safe flags when running on WSL:\n\n```\n--disable-gpu\n--disable-software-rasterizer\n--disable-dev-shm-usage\n```\n\nOn non-WSL systems, it passes through to `@playwright/mcp` unchanged. No performance impact — GPU acceleration is meaningless for headless browser automation.\n\n## Installation\n\n### Claude Code (recommended)\n\nAdd to your Claude Code settings (`.claude/settings.json` or global settings):\n\n```json\n{\n  \"mcpServers\": {\n    \"playwright\": {\n      \"command\": \"npx\",\n      \"args\": [\"playwright-mcp-wsl@latest\"]\n    }\n  }\n}\n```\n\nThis replaces the default `@playwright/mcp` entry.\n\n### Manual / Other MCP Hosts\n\n```bash\nnpx playwright-mcp-wsl@latest\n```\n\nAll `@playwright/mcp` CLI flags are supported:\n\n```bash\nnpx playwright-mcp-wsl@latest --headless --viewport-size 1440x900\n```\n\n### Programmatic\n\n```js\nconst { createConnection } = require('playwright-mcp-wsl');\n// Same API as @playwright/mcp, with WSL-safe defaults\n```\n\n## How It Works\n\n1. **Detects WSL** by reading `/proc/version` for Microsoft/WSL kernel strings\n2. **If WSL**: sets `PLAYWRIGHT_MCP_CONFIG` to a bundled config that adds `--disable-gpu` and related flags to Chromium launch args\n3. **If not WSL**: passes through to `@playwright/mcp` with zero modifications\n4. **If user has custom config**: merges WSL-safe args into existing config (no overwrite)\n\n## What It Disables\n\n| Flag | Why |\n|------|-----|\n| `--disable-gpu` | Prevents GPU memory allocation through the dxg bridge |\n| `--disable-software-rasterizer` | Prevents fallback software GPU that still uses dxg |\n| `--disable-dev-shm-usage` | Uses `/tmp` instead of `/dev/shm` (often undersized on WSL) |\n\n## What It Doesn't Affect\n\n- Page rendering quality (identical for headless automation)\n- JavaScript execution\n- Network requests\n- Screenshot quality\n- DOM interaction\n- Any Playwright MCP functionality\n\n## Compatibility\n\n- WSL1 and WSL2\n- Windows 10 and Windows 11\n- Node.js 18+\n- All `@playwright/mcp` versions >= 0.0.60\n- Claude Code, Cursor, Windsurf, or any MCP-compatible host\n\n## Verifying It Works\n\nWhen running on WSL, you'll see in stderr:\n\n```\n[playwright-mcp-wsl] Detected WSL2 + dxg bridge. Injecting GPU-safe config.\n```\n\nWhen running on non-WSL:\n\n```\n[playwright-mcp-wsl] Not running in WSL. Passing through to @playwright/mcp.\n```\n\n## Background\n\nThis package was created after diagnosing cascading WSL crashes during parallel browser automation with Claude Code's PAI system. The root cause was Chromium's GPU memory allocation through WSL2's `dxg` (DirectX Graphics) bridge — a kernel-level GPU passthrough layer not designed for concurrent headless browser load.\n\nCrash signature in `dmesg`:\n```\nmisc dxg: dxgk: dxgvmb_send_create_allocation: send_create_allocation failed ffffffb5\nmisc dxg: dxgk: dxgkio_create_allocation: Ioctl failed: -75\nchrome: potentially unexpected fatal signal 11\nWSL (CaptureCrash): Capturing crash for pid: ..., executable: chrome, signal: 11\n```\n\n## License\n\nApache-2.0 — same as Playwright.\n","readmeFilename":"README.md","_rev":"1-979fccaa2efb3da9042b09a0ed41b996"}