GDD - AI-Controlled Browser Farm

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.

---

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 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 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.

---

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

Docker

# 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 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.

Config file locations

Global and project configs are merged — servers from both are available simultaneously. Changes are picked up only when restarting the AI client session.

VS Code-based IDEs (Windsurf, Antigravity, Copilot)

VS Code-based IDEs use a different config format than Claude Code / Cursor.

Project config — .vscode/mcp.json:

{

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

Global config — open via Cmd+Shift+P → "Open User Settings (JSON)":

{

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

Global settings.json location: macOS — ~/Library/Application Support/ /User/settings.json, Linux — ~/.config/ /User/settings.json, Windows — %APPDATA%/ /User/settings.json. Replace with your editor name (Code, Windsurf, Antigravity, etc.).

stdio-proxy alternative (.vscode/mcp.json):

{

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

Permissions (Claude Code)

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": [ "mcpgdd*" ] } }

This single wildcard covers all 39 GDD tools. Restart Claude Code after editing.

Auto-launch via stdio proxy (alternative)

Proxy scripts start GDD automatically when your AI client connects:

Windows:

{

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

Linux / macOS:

{

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

Add "--headless" to the args array for CI/CD.

Tip: On first launch, GDD downloads Chromium (~80 MB). If your AI client times out, run GDD manually first, then reconnect.

Autostart as service (macOS / Linux)

macOS (launchd):

bash Scripts/install-launchd.sh            # headed (default)

bash Scripts/install-launchd.sh --headless # for CI/CD

Manage: launchctl list | grep gdd / bash Scripts/install-launchd.sh --uninstall

Linux (systemd):

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

Direct HTTP (without AI client)

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}}}'

GDD uses standard JSON-RPC 2.0 — works with curl, Python, Node.js, or any HTTP client.

---

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 o