GDD (Giggly-Dazzling-Duckling)

AI-controlled browser farm — run N isolated Chromium instances with 36 MCP tools for device emulation, screenshots, network/geolocation simulation, and diagnostics. Cross-platform: Windows GUI + headed/headless on Linux/macOS.

AI-controlled browser farm on your machine
Simulate multiple real users across 22 device types — test your site like it's launch day.

You:Open 3 iPhones and a desktop, navigate to myapp.com, test the signup form on all devices

Claude Codecreates 4 browsers with device emulation, navigates each to your app, fills in the form, takes screenshots, checks console for errors — all in parallel.

gdd_add_players(3, device="iPhone 15 Pro") → players [1, 2, 3] gdd_add_players(1, device="Desktop 1080p") → player [4] gdd_navigate(1, "https://myapp.com") → all 4 browsers open your app gdd_tap(1, "#signup-btn") → taps signup on iPhone gdd_screenshot(1) → captures the result gdd_get_console(1, level="error") → checks for JS errors

GDD comes in two flavours. TheServeris headless — it's just the MCP backend, runs anywhere (including boxes with no display), and is all you need for pure AI automation. TheDesktop appadds a GUI: a live grid of browser thumbnails you can click into to take over a session by hand. The Server runs on port9700, the Desktop app on9800— so you can run both side by side.

Desktop app (GUI)— a live grid of browser thumbnails you can click into:

The Windows app uses WebView2; the Linux/macOS app (built with Avalonia) drives real Chromium windows parked off-screen. Self-contained binary, ~70 MB. No .NET installation needed. Chromium downloads automatically on first launch.

curl -sL https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Linux.tar.gz | tar xz && chmod +x GDD.Headless && ./GDD.Headless

# Run (headless, port 9700) docker run -p 9700:9700 ghcr.io/cap-of-tea/gdd # Or build locally docker build -t gdd . docker run -p 9700:9700 gdd

The Docker image runs in headless mode with all Chromium dependencies pre-installed.

By default, browsers launch inheadedmode (visible windows). Add--headlessfor CI/CD. Other flags:--stealthand--stealth-maxfor anti-bot masking,--updateto self-update,--versionand--help. TheConfigurationsection below lists every flag and environment variable.

Add to.mcp.jsonand restart your AI client:

{ "mcpServers": { "gdd": { "url": "http://localhost:9700/mcp" } } }

That's it. Start GDD, tell Claude or Cursor to test your app.

Claude Desktop users:Download the.mcpbfile fromReleasesand open it — GDD installs as a one-click desktop extension. No manual config needed.

{ "servers": { "gdd": { "type": "http", "url": "http://localhost:9700/mcp" } } }

{ "mcp": { "servers": { "gdd": { "type": "http", "url": "http://localhost:9700/mcp" } } } }

{ "servers": { "gdd": { "type": "stdio", "command": "bash", "args": ["/absolute/path/to/Scripts/mcp-proxy.sh"] } } }

By default, Claude Code asks for confirmation on every MCP tool call. To allow GDD tools without prompts, add to~/.claude/settings.json:

{ "permissions": { "allow": [ "mcp__gdd__" ] } }

{ "mcpServers": { "gdd": { "command": "powershell", "args": ["-ExecutionPolicy", "Bypass", "-File", "C:/path/to/Scripts/mcp-proxy.ps1"] } } }

{ "mcpServers": { "gdd": { "command": "bash", "args": ["/path/to/Scripts/mcp-proxy.sh"] } } }

bash Scripts/install-launchd.sh # headed (default) bash Scripts/install-launchd.sh --headless # for CI/CD

mkdir -p ~/.config/systemd/user cat > ~/.config/systemd/user/gdd.service << 'EOF' [Unit] Description=GDD Multi-Browser Testing Server [Service] ExecStart=/path/to/GDD.Headless WorkingDirectory=/path/to/gdd-directory Restart=on-failure [Install] WantedBy=default.target EOF systemctl --user daemon-reload systemctl --user enable --now gdd

curl -X POST http://localhost:9700/mcp -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"gdd_add_players","arguments":{"count":1}}}'

- Multi-device— Run N isolated Chromium instances with 22 device presets (phones, tablets, desktops)
- AI-native— 39 MCP tools for Claude Code, Cursor, or any MCP-compatible client
- Cross-platform— Native GUI with a live video wall on Windows, Linux & macOS, plus a headless server for CI/CD
- Full interaction— Navigate, tap, type, press keys and shortcuts, drag, swipe, scroll, hover, handle dialogs, take screenshots
- Real keyboard— Typing sends genuine, trusted keystrokes (the full keydown→input chain), so input masks, autocomplete andmaxlengthbehave exactly as they do for a real user, and rich-text (contenteditable) editors work;gdd_presshandles single keys and shortcuts like Enter, Tab, Escape and Ctrl+A
- Physical keyboard layouts— Keystrokes carry the realcode/keyCodeof the emulated locale's keyboard: Russian ЙЦУКЕН puts «а» on the physicalKeyF, French AZERTY and German QWERTZ remap their keys, dead-key accents and AltGr symbols work. The layout followsgdd_set_languageautomatically (US, RU, DE, FR)
- Human-like input—humanize=truedrives a continuous cursor path (cubic Bézier with easing and micro-jitter) that carries over between clicks, hovers and drags; taps fire a single device-appropriate input (touchor*mouse), never both
- Anti-bot stealth— opt-in--stealthmasks the usual automation tells (navigator.webdriver, etc.);--stealth-maxadds headless/datacenter evasions (coherent user-agent client hints, a plausible WebGL vendor, realistic device metrics) — on a headless container this halved CreepJS's headless score
- Proxy support— Route every browser through an upstream proxy withGDD_PROXY(with optional auth)
- Header rewriting—gdd_set_headerscan stripX-Frame-Options/CSPframe-ancestorsto load a site in an iframe, or add/replace response headers
- Device emulation— Screen size, DPR, touch, user agent, geolocation, timezone, language
- Network control— Simulate 4G, Fast 3G, Slow 3G, or offline per browser
- Diagnostics— Console errors, network traffic, performance metrics, push notifications
- Error beacon— Every tool response warns about JS errors across all browsers automatically
- Docker-ready— Official image on GHCR (ghcr.io/cap-of-tea/gdd), listed on theMCP Registry
- Self-updating— Built-in version check and one-command update

Client (AI agent / curl / script) │ POST /mcp (JSON-RPC 2.0) ▼ McpServer (:9700) Streamable HTTP + SSE │ ▼ McpToolRegistry (39 tools) Player · Navigation · Interaction · Read Emulation · Auth · State · Diagnostics │ ▼ IPlayerManager MainViewModel (WPF) / DesktopPlayerManager (Avalonia) / HeadlessPlayerManager │ ▼ IBrowserEngine Instances WebView2 (Win GUI) | Playwright (Desktop GUI + headed/headless server) Each: own profile, CDP session, emulation

BrowserXn.sln ├── src/ │ ├── GDD.Core/ ← Shared library (net8.0) │ │ ├── Abstractions/ ← IBrowserEngine, IPlayerManager, ... │ │ ├── Mcp/ ← MCP server, tools, protocol │ │ ├── Models/ ← Device, Location, Network presets │ │ ├── Services/ ← CDP, Emulation, Monitoring services │ │ └── Collections/ ← RingBuffer │ ├── BrowserXn/ ← Windows GUI (WPF + WebView2) │ │ ├── Engines/ ← WebView2ControlAdapter │ │ ├── ViewModels/ ← MVVM (MainViewModel : IPlayerManager) │ │ ├── Views/ ← XAML + VideoWallPanel │ │ └── ... │ ├── GDD.Desktop/ ← Linux/macOS GUI (Avalonia + Playwright) │ │ ├── Engines/ ← PlaywrightHeadedEngine (headed, parked off-screen) │ │ ├── ViewModels/ ← MainViewModel (DesktopPlayerManager) │ │ ├── Views/ ← AXAML + VideoWallPanel │ │ └── Scripts/ ← mcp-proxy.sh, setup-macos.sh, install-deps.sh │ └── GDD.Headless/ ← Cross-platform server (Playwright) │ ├── Engines/ ← PlaywrightEngine │ ├── Platform/ ← HeadlessPlayerManager │ └── Scripts/ ← mcp-proxy.sh, mcp-proxy.ps1 └── .github/workflows/ ← CI/CD (8 build targets + auto-release)

{ "GDD": { "FrontendUrl": "about:blank", "BackendUrl": "http://localhost:8080/api/v1", "BotToken": "", "McpPort": 9700, "DataFolderRoot": "", "Stealth": false } }

# Windows GUI (requires Windows 10/11 + WebView2) dotnet publish src/BrowserXn/BrowserXn.csproj -c Release -p:PublishSingleFile=true -o ./publish/win-gui # Cross-platform headless dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r linux-x64 --self-contained -o ./publish/linux-x64 dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r osx-arm64 --self-contained -o ./publish/osx-arm64 dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r win-x64 --self-contained -o ./publish/win-x64

- GDD-MANUAL.md— Full usage manual with workflow examples
- GDD-ARCHITECTURE.md— Architecture deep-dive
- GDD-PROMPT.md— Claude agent instructions for MCP integration
- DEPLOY-RAILWAY.md— Host GDD as a remote MCP server on Railway (behind a token-auth proxy)
- CONTRIBUTING.md— Contribution guidelines

Source Available — Non-Commercial. Free for personal use, education, and research. Commercial use requires a paid license. SeeLICENSEfor full terms.

Commercial licensing:2vsmirnov@gmail.com

Bring the full power of BrowserStack’s Test Platform to your AI tools, making testing faster and easier for every developer and tester on your team.