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/<IDE>/User/settings.json, Linux — ~/.config/<IDE>/User/settings.json, Windows — %APPDATA%/<IDE>/User/settings.json. Replace <IDE> 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": [
      "mcp__gdd__*"
    ]
  }
}

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

---

Device Presets (22)

Phones (11)

Tablets (6)

Desktops (5)

---

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

Project Structure

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)

---

Configuration

appsettings.json next to the executable:

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

Command-line flags

Environment variables

Handy for Docker and CI, where an appsettings.json file is awkward:

Building from Source

Requires .NET 8 SDK.

# 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

Chromium installs automatically on first run.

---

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

Privacy Policy

GDD runs entirely on your local machine. No telemetry, no analytics, no data collection.

• No data leaves your machine — all browser profiles, screenshots, logs, and cookies stay in local storage
• Browser profiles — stored in %LOCALAPPDATA%\GDD\Profiles (Windows) or ~/.local/share/GDD/Profiles (Linux/macOS)
• No third-party services — GDD does not contact any external APIs except GitHub Releases for optional update checks
• Update checks — gdd_check_update makes a single read-only request to api.github.com. Opt out by not calling the tool, or set CheckForUpdates: false in appsettings.json
• MCP server — listens on localhost only (default port 9700), never exposed to the network

Contact: 2vsmirnov@gmail.com

---

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: 2vsmirnov@gmail.com