\n AI-controlled browser farm on your machine \n Simulate multiple real users across 22 device types — test your site like it's launch day.\n
\n\n
\n \n \n \n \n \n
\n
\n \n \n
\n\n---\n\n## How It Works\n\n> **You:** Open 3 iPhones and a desktop, navigate to myapp.com, test the signup form on all devices\n>\n> **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.\n\n```text\ngdd_add_players(3, device=\"iPhone 15 Pro\") → players [1, 2, 3]\ngdd_add_players(1, device=\"Desktop 1080p\") → player [4]\ngdd_navigate(1, \"https://myapp.com\") → all 4 browsers open your app\ngdd_tap(1, \"#signup-btn\") → taps signup on iPhone\ngdd_screenshot(1) → captures the result\ngdd_get_console(1, level=\"error\") → checks for JS errors\n```\n\nGDD 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`.\n\n
\n \n
\n\n---\n\n## Install\n\nGDD 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.\n\n**Server (headless)** — the MCP backend:\n\n| Platform | Download | Run |\n|----------|----------|-----|\n| **Linux** | [GDD-Server-Linux.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Linux.tar.gz) | `chmod +x GDD.Headless && ./GDD.Headless` |\n| **macOS ARM** | [GDD-Server-macOS-ARM.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-ARM.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Headless` |\n| **macOS Intel** | [GDD-Server-macOS-Intel.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-Intel.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Headless` |\n| **Windows** | [GDD-Server-Windows.zip](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Windows.zip) | `.\\GDD.Headless.exe` |\n| **Docker** | `ghcr.io/cap-of-tea/gdd` | `docker run -p 9700:9700 ghcr.io/cap-of-tea/gdd` |\n| **Claude Desktop** | [Win](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Windows.mcpb) / [Mac ARM](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-ARM.mcpb) / [Mac Intel](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-macOS-Intel.mcpb) (.mcpb) | Open `.mcpb` file — installs as desktop extension |\n\n**Desktop app (GUI)** — a live grid of browser thumbnails you can click into:\n\n| Platform | Download | Run |\n|----------|----------|-----|\n| **Windows** | [GDD-Desktop-Windows.zip](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-Windows.zip) | Extract, run `GDD.exe` ([WebView2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) required) |\n| **Linux** | [GDD-Desktop-Linux.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-Linux.tar.gz) | `bash Scripts/install-deps.sh && ./GDD.Desktop` |\n| **macOS ARM** | [GDD-Desktop-macOS-ARM.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-macOS-ARM.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Desktop` |\n| **macOS Intel** | [GDD-Desktop-macOS-Intel.tar.gz](https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Desktop-macOS-Intel.tar.gz) | `bash Scripts/setup-macos.sh && ./GDD.Desktop` |\n\nThe 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.\n\n**One-liner (Linux):**\n\n```bash\ncurl -sL https://github.com/Cap-of-tea/GDD/releases/latest/download/GDD-Server-Linux.tar.gz | tar xz && chmod +x GDD.Headless && ./GDD.Headless\n```\n\n\nDocker\n\n```bash\n# Run (headless, port 9700)\ndocker run -p 9700:9700 ghcr.io/cap-of-tea/gdd\n\n# Or build locally\ndocker build -t gdd .\ndocker run -p 9700:9700 gdd\n```\n\nThe Docker image runs in headless mode with all Chromium dependencies pre-installed.\n\n\n\nBy 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.\n\n---\n\n## Connect to Your AI Client\n\nAdd to `.mcp.json` and restart your AI client:\n\n```json\n{\n \"mcpServers\": {\n \"gdd\": {\n \"url\": \"http://localhost:9700/mcp\"\n }\n }\n}\n```\n\nThat's it. Start GDD, tell Claude or Cursor to test your app.\n\n> **Claude Desktop users:** Download the `.mcpb` file from [Releases](https://github.com/Cap-of-tea/GDD/releases/latest) and open it — GDD installs as a one-click desktop extension. No manual config needed.\n\n\nConfig file locations\n\n| Client | Project config | Global config |\n| ------ | -------------- | ------------- |\n| Claude Code | `/.mcp.json` | `~/.claude/.mcp.json` |\n| Cursor | `/.cursor/mcp.json` | `~/.cursor/mcp.json` |\n| VS Code / Windsurf / Antigravity | `/.vscode/mcp.json` | IDE `settings.json` |\n\nGlobal and project configs are merged — servers from both are available simultaneously. Changes are picked up only when restarting the AI client session.\n\n\n\n\nVS Code-based IDEs (Windsurf, Antigravity, Copilot)\n\nVS Code-based IDEs use a different config format than Claude Code / Cursor.\n\n**Project config** — `.vscode/mcp.json`:\n\n```json\n{\n \"servers\": {\n \"gdd\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:9700/mcp\"\n }\n }\n}\n```\n\n**Global config** — open via `Cmd+Shift+P` → \"Open User Settings (JSON)\":\n\n```json\n{\n \"mcp\": {\n \"servers\": {\n \"gdd\": {\n \"type\": \"http\",\n \"url\": \"http://localhost:9700/mcp\"\n }\n }\n }\n}\n```\n\nGlobal `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.).\n\n**stdio-proxy** alternative (`.vscode/mcp.json`):\n\n```json\n{\n \"servers\": {\n \"gdd\": {\n \"type\": \"stdio\",\n \"command\": \"bash\",\n \"args\": [\"/absolute/path/to/Scripts/mcp-proxy.sh\"]\n }\n }\n}\n```\n\n\n\n\nPermissions (Claude Code)\n\nBy default, Claude Code asks for confirmation on every MCP tool call. To allow GDD tools without prompts, add to `~/.claude/settings.json`:\n\n```json\n{\n \"permissions\": {\n \"allow\": [\n \"mcp__gdd__*\"\n ]\n }\n}\n```\n\nThis single wildcard covers all 39 GDD tools. Restart Claude Code after editing.\n\n\n\n\nAuto-launch via stdio proxy (alternative)\n\nProxy scripts start GDD automatically when your AI client connects:\n\n**Windows:**\n\n```json\n{\n \"mcpServers\": {\n \"gdd\": {\n \"command\": \"powershell\",\n \"args\": [\"-ExecutionPolicy\", \"Bypass\", \"-File\", \"C:/path/to/Scripts/mcp-proxy.ps1\"]\n }\n }\n}\n```\n\n**Linux / macOS:**\n\n```json\n{\n \"mcpServers\": {\n \"gdd\": {\n \"command\": \"bash\",\n \"args\": [\"/path/to/Scripts/mcp-proxy.sh\"]\n }\n }\n}\n```\n\nAdd `\"--headless\"` to the `args` array for CI/CD.\n\n> **Tip:** On first launch, GDD downloads Chromium (~80 MB). If your AI client times out, run GDD manually first, then reconnect.\n\n\n\n\nAutostart as service (macOS / Linux)\n\n**macOS (launchd):**\n\n```bash\nbash Scripts/install-launchd.sh # headed (default)\nbash Scripts/install-launchd.sh --headless # for CI/CD\n```\n\nManage: `launchctl list | grep gdd` / `bash Scripts/install-launchd.sh --uninstall`\n\n**Linux (systemd):**\n\n```bash\nmkdir -p ~/.config/systemd/user\ncat > ~/.config/systemd/user/gdd.service << 'EOF'\n[Unit]\nDescription=GDD Multi-Browser Testing Server\n[Service]\nExecStart=/path/to/GDD.Headless\nWorkingDirectory=/path/to/gdd-directory\nRestart=on-failure\n[Install]\nWantedBy=default.target\nEOF\n\nsystemctl --user daemon-reload\nsystemctl --user enable --now gdd\n```\n\n\n\n\nDirect HTTP (without AI client)\n\n```bash\ncurl -X POST http://localhost:9700/mcp -H \"Content-Type: application/json\" \\\n -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"gdd_add_players\",\"arguments\":{\"count\":1}}}'\n```\n\nGDD uses standard JSON-RPC 2.0 — works with `curl`, Python, Node.js, or any HTTP client.\n\n\n\n---\n\n## Features\n\n- **Multi-device** — Run N isolated Chromium instances with 22 device presets (phones, tablets, desktops)\n- **AI-native** — 39 MCP tools for Claude Code, Cursor, or any MCP-compatible client\n- **Cross-platform** — Native GUI with a live video wall on Windows, Linux & macOS, plus a headless server for CI/CD\n- **Full interaction** — Navigate, tap, type, press keys and shortcuts, drag, swipe, scroll, hover, handle dialogs, take screenshots\n- **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\n- **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)\n- **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\n- **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\n- **Proxy support** — Route every browser through an upstream proxy with `GDD_PROXY` (with optional auth)\n- **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\n- **Device emulation** — Screen size, DPR, touch, user agent, geolocation, timezone, language\n- **Network control** — Simulate 4G, Fast 3G, Slow 3G, or offline per browser\n- **Diagnostics** — Console errors, network traffic, performance metrics, push notifications\n- **Error beacon** — Every tool response warns about JS errors across all browsers automatically\n- **Docker-ready** — Official image on GHCR (`ghcr.io/cap-of-tea/gdd`), listed on the [MCP Registry](https://registry.modelcontextprotocol.io)\n- **Self-updating** — Built-in version check and one-command update\n\n---\n\n## MCP Tools (39)\n\n### Player Management\n\n| Tool | Description |\n|------|-------------|\n| `gdd_add_players` | Add N browser instances with optional device preset |\n| `gdd_remove_player` | Remove a browser instance by player ID |\n| `gdd_list_windows` | List all active browsers with current state |\n\n### Navigation\n\n| Tool | Description |\n|------|-------------|\n| `gdd_navigate` | Navigate to a URL |\n| `gdd_wait` | Wait for a CSS selector to appear (with timeout) |\n| `gdd_reload` | Reload page (`hard=true` bypasses cache) |\n| `gdd_back` | Navigate back |\n| `gdd_forward` | Navigate forward |\n\n### Interaction\n\n| Tool | Description |\n|------|-------------|\n| `gdd_tap` | Tap element by CSS selector or coordinates; sends a single device-appropriate input (touch on touch devices, mouse on desktop), never both. `humanize=true` adds a continuous human-like cursor path |\n| `gdd_swipe` | Swipe gesture (up/down/left/right) |\n| `gdd_drag` | Drag an element to (x, y) or onto another element via real pointer events (drives dnd-kit & HTML5 drag-and-drop) |\n| `gdd_scroll` | Scroll page or element |\n| `gdd_type` | Type text with real, trusted keystrokes (CDP dispatchKeyEvent — masks, autocomplete and maxlength behave as for a real user; works on contenteditable). Physical key codes follow the emulated layout (US/RU/DE/FR); `humanize=true` adds per-key jitter; `paste=true` inserts in one shot |\n| `gdd_press` | Press a single key or shortcut (Enter, Tab, Escape, Arrow keys, F1–F12, or a character) with optional modifiers (Control/Alt/Shift/Meta); character keys follow the emulated layout |\n| `gdd_hover` | Hover over element. `humanize=true` adds a continuous human-like cursor path |\n| `gdd_select` | Select option from `
![\"GDD\"](\"Design/giggly-dazzling-duckling.png\")
\n![\"Release\"](\"https://img.shields.io/github/v/release/Cap-of-tea/GDD?style=flat-square&color=blue\")
![\"Platforms\"](\"https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-0078D6?style=flat-square\"){kind=icon}
![\"MCP\"](\"https://img.shields.io/badge/MCP-compatible-44CC11?style=flat-square\"){kind=icon}
![\"MCP](\"https://img.shields.io/badge/MCP%20Registry-listed-44CC11?style=flat-square\"){kind=icon}
![\"License\"](\"https://img.shields.io/badge/license-free%20for%20personal%20use-blue?style=flat-square\"){kind=icon}
![\"Claude](\"https://img.shields.io/badge/Works%20with-Claude%20Code-F97316?style=flat-square\"){kind=icon}
![\"Cursor\"](\"https://img.shields.io/badge/Works%20with-Cursor-007ACC?style=flat-square\"){kind=icon}
![\"GDD](\"Design/gdd-video-wall.png\")
\n