GDD - AI-Controlled Browser Farm

[GDD]

GDD — Giggly-Dazzling-Duckling

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

[Release] [Platforms] [MCP] [MCP Registry] [License]

[Claude Code] [Cursor]

How It Works

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

Claude Code creates 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 appgdd_tap(1, "#signup-btn")                     → taps signup on iPhonegdd_screenshot(1)                             → captures the resultgdd_get_console(1, level="error")             → checks for JS errors

GDD runs N isolated Chromium instances, each with its own profile, cookies, device emulation, geolocation, and network conditions. It exposes 39 MCP tools via HTTP on localhost:9700.

[GDD Video Wall — 3 devices testing simultaneously]

Install

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

Server (headless) — the MCP backend:

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.

One-liner (Linux):

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 locallydocker build -t gdd .docker run -p 9700:9700 gdd

By default, browsers launch in headed mode (visible windows). Add --headless for CI/CD. Other flags: --stealth and --stealth-max for anti-bot masking, --update to self-update, --version and --help. The Configuration section below lists every flag and environment variable.

Connect to Your AI Client

Add to .mcp.json and 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 .mcpb file from Releases and 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"]    }  }}

{  "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/usercat > ~/.config/systemd/user/gdd.service << 'EOF'[Unit]Description=GDD Multi-Browser Testing Server[Service]ExecStart=/path/to/GDD.HeadlessWorkingDirectory=/path/to/gdd-directoryRestart=on-failure[Install]WantedBy=default.targetEOF
systemctl --user daemon-reloadsystemctl --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}}}'

Features

• 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 and maxlength behave exactly as they do for a real user, and rich-text (contenteditable) editors work; gdd_press handles single keys and shortcuts like Enter, Tab, Escape and Ctrl+A
• Physical keyboard layouts — Keystrokes carry the real code/keyCode of the emulated locale's keyboard: Russian ЙЦУКЕН puts «а» on the physical KeyF, French AZERTY and German QWERTZ remap their keys, dead-key accents and AltGr symbols work. The layout follows gdd_set_language automatically (US, RU, DE, FR)
• Human-like input — humanize=true drives 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 (touch or mouse), never both
• Anti-bot stealth — opt-in --stealth masks the usual automation tells (navigator.webdriver, etc.); --stealth-max adds 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 with GDD_PROXY (with optional auth)
• Header rewriting — gdd_set_headers can strip X-Frame-Options/CSP frame-ancestors to 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 the MCP Registry
• Self-updating — Built-in version check and one-command update

MCP Tools (39)

Player Management

Navigation

Interaction

Reading & Screenshots

Emulation

State & Diagnostics

Auth & Execution

Browser Storage

Help & Updates

Architecture

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

Editions

GDD ships as three apps over one shared core. The two GUIs differ only in the desktop toolkit (WebView2 on Windows, Avalonia on Linux/macOS); all three expose the same 39 MCP tools.

Tech Stack

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 headlessdotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r linux-x64 --self-contained -o ./publish/linux-x64dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r osx-arm64 --self-contained -o ./publish/osx-arm64dotnet publish src/GDD.Headless/GDD.Headless.csproj -c Release -r win-x64 --self-contained -o ./publish/win-x64

Documentation

• GDD-MANUAL.md — Full usage manual with workflow examples
• GDD-ARCHITECTURE.md — Architecture deep-dive
• GDD-PROMPT.md — Claude agent instructions for MCP integration
• docker-compose.prod.yml — Self-host GDD as a remote MCP server behind a Caddy bearer-token proxy
• CONTRIBUTING.md — Contribution guidelines

Privacy

License

imVS©, free for personal use.

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

Commercial licensing: [email protected]