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

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

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

{
  "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/user
cat > ~/.config/systemd/user/gdd.service 

Direct HTTP (without AI client)

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](https://registry.modelcontextprotocol.io)
- **Self-updating** — Built-in version check and one-command update

---

## MCP Tools (39)

### Player Management

| Tool | Description |
|------|-------------|
| `gdd_add_players` | Add N browser instances with optional device preset |
| `gdd_remove_player` | Remove a browser instance by player ID |
| `gdd_list_windows` | List all active browsers with current state |

### Navigation

| Tool | Description |
|------|-------------|
| `gdd_navigate` | Navigate to a URL |
| `gdd_wait` | Wait for a CSS selector to appear (with timeout) |
| `gdd_reload` | Reload page (`hard=true` bypasses cache) |
| `gdd_back` | Navigate back |
| `gdd_forward` | Navigate forward |

### Interaction

| Tool | Description |
|------|-------------|
| `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 |
| `gdd_swipe` | Swipe gesture (up/down/left/right) |
| `gdd_drag` | Drag an element to (x, y) or onto another element via real pointer events (drives dnd-kit & HTML5 drag-and-drop) |
| `gdd_scroll` | Scroll page or element |
| `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 |
| `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 |
| `gdd_hover` | Hover over element. `humanize=true` adds a continuous human-like cursor path |
| `gdd_select` | Select option from `` dropdown |
| `gdd_dialog` | Handle JS alert/confirm/prompt dialogs |

### Reading & Screenshots

| Tool | Description |
|------|-------------|
| `gdd_read` | Read text content of an element |
| `gdd_read_all` | Read text from all matching elements |
| `gdd_screenshot` | Capture JPEG screenshot at CSS pixel resolution |

### Emulation

| Tool | Description |
|------|-------------|
| `gdd_set_device` | Set device preset (22 devices: phones, tablets, desktops) |
| `gdd_set_viewport` | Set custom viewport dimensions |
| `gdd_set_location` | Set geolocation, timezone, and locale |
| `gdd_set_network` | Set network conditions (4G, 3G, offline) |
| `gdd_set_language` | Set browser language |
| `gdd_set_headers` | Rewrite response headers — strip X-Frame-Options/CSP to allow framing |

### State & Diagnostics

| Tool | Description |
|------|-------------|
| `gdd_get_state` | Browser state: URL, title, device, auth status |
| `gdd_get_console` | Console output and uncaught exceptions |
| `gdd_get_network` | Network requests with timing and status |
| `gdd_get_notifications` | Received push notifications |
| `gdd_get_performance` | Performance metrics (JS heap, DOM nodes, FPS) |
| `gdd_clear_logs` | Clear console and/or network logs |

### Auth & Execution

| Tool | Description |
|------|-------------|
| `gdd_quick_auth` | Auto-register and login with generated credentials |
| `gdd_execute_js` | Execute JavaScript and return result |

### Browser Storage

| Tool | Description |
|------|-------------|
| `gdd_storage` | Read/write/clear localStorage/sessionStorage |
| `gdd_cookies` | Read or clear browser cookies |

### Help & Updates

| Tool | Description |
|------|-------------|
| `gdd_get_manual` | Full GDD manual for AI self-learning |
| `gdd_check_update` | Check for newer versions |
| `gdd_update` | Download and install update (restarts GDD) |

---

Device Presets (22)

### Phones (11)

| Device | Resolution | Scale | Touch |
|--------|-----------|-------|-------|
| iPhone SE | 375 x 667 | 2.0x | Yes |
| iPhone 14 | 390 x 844 | 3.0x | Yes |
| iPhone 15 Pro | 393 x 852 | 3.0x | Yes |
| iPhone 15 Pro Max | 430 x 932 | 3.0x | Yes |
| iPhone 16 Pro | 402 x 874 | 3.0x | Yes |
| iPhone 16 Pro Max | 440 x 956 | 3.0x | Yes |
| Pixel 9 | 412 x 915 | 2.625x | Yes |
| Pixel 9 Pro | 412 x 915 | 2.625x | Yes |
| Galaxy S24 | 360 x 780 | 3.0x | Yes |
| Galaxy S24 Ultra | 412 x 915 | 3.0x | Yes |
| OnePlus 12 | 412 x 915 | 3.5x | Yes |

### Tablets (6)

| Device | Resolution | Scale |
|--------|-----------|-------|
| iPad Mini | 744 x 1133 | 2.0x |
| iPad Air | 820 x 1180 | 2.0x |
| iPad Pro 11" | 834 x 1194 | 2.0x |
| iPad Pro 13" | 1024 x 1366 | 2.0x |
| Galaxy Tab S9 | 800 x 1280 | 2.0x |
| Pixel Tablet | 800 x 1280 | 2.0x |

### Desktops (5)

| Device | Resolution | Scale |
|--------|-----------|-------|
| Laptop HD | 1366 x 768 | 1.0x |
| Laptop HiDPI | 1440 x 900 | 2.0x |
| Desktop 1080p | 1920 x 1080 | 1.0x |
| Desktop 1440p | 2560 x 1440 | 1.0x |
| Desktop 4K | 3840 x 2160 | 2.0x |

---

## Architecture

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

| | Windows GUI | Desktop GUI | Server |
|---|---|---|---|
| Binary | `GDD.exe` | `GDD.Desktop` | `GDD.Headless` (add `--headless` for no windows) |
| Engine | WebView2 | Playwright (headed) | Playwright (headed/headless) |
| UI | WPF video wall | Avalonia video wall | none — HTTP API only |
| MCP port | 9700 | 9800 | 9700 |
| Platforms | Windows | Linux, macOS | Windows, Linux, macOS |

### Tech Stack

| Layer | Technology |
|-------|-----------|
| Runtime | .NET 8.0 (self-contained) |
| UI (Windows) | WPF + CommunityToolkit.Mvvm |
| UI (Linux/macOS) | Avalonia + CommunityToolkit.Mvvm |
| Browser (Windows GUI) | Microsoft WebView2 |
| Browser (Desktop GUI + Server) | Microsoft Playwright |
| Protocol | MCP (Model Context Protocol) |
| Browser Control | Chrome DevTools Protocol (CDP) |
| Logging | Serilog |

Project Structure

---

Configuration

`appsettings.json` next to the executable:

| Key | Description | Default |
|-----|-------------|---------|
| `FrontendUrl` | Default URL for new browsers | `about:blank` |
| `BackendUrl` | Backend API for auth service | `http://localhost:8080/api/v1` |
| `BotToken` | Telegram bot token (for TG testing) | — |
| `McpPort` | MCP server port (auto-fallback +1..+9) | `9700` |
| `DataFolderRoot` | Browser profile storage root | `%LOCALAPPDATA%\GDD\Profiles` (Win), `~/.local/share/GDD/Profiles` (Linux/macOS) |
| `Headed` | Visible browser windows | `true` (override with `--headless`) |
| `Stealth` | Opt-in anti-bot masking — launches Chromium with AutomationControlled disabled and hides the usual automation tells (`navigator.webdriver`, etc.). Playwright engines (GDD.Desktop, GDD Server) only | `false` |

### Command-line flags

| Flag | Description |
|------|-------------|
| `--headed` | Visible browser windows (default) |
| `--headless` | No UI — for CI/CD |
| `--stealth` | Enable anti-bot masking (same as `GDD_STEALTH=true`) |
| `--stealth-max` | Full stealth — client-hints UA metadata, WebGL/device/timezone spoofing; implies `--stealth` (same as `GDD_STEALTH_MAX=true`) |
| `--update` | Check for a newer version and install it if available |
| `--version` | Print the version and exit |
| `--help` | Show usage and exit |

### Environment variables

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

| Variable | Description |
|----------|-------------|
| `GDD_STEALTH` | `true`/`1` to enable anti-bot masking (same as `--stealth`) |
| `GDD_STEALTH_MAX` | `true`/`1` for full stealth (same as `--stealth-max`) |
| `GDD_PROXY` | Upstream proxy for every browser, e.g. `http://host:3128` or `socks5://host:1080` (Server / Playwright engines) |
| `GDD_PROXY_USER` / `GDD_PROXY_PASS` | Credentials for an authenticated proxy |
| `GDD_CHROME_CHANNEL` | Launch an installed Chrome build (e.g. `chrome`, `chrome-beta`) instead of bundled Chromium |
| `GDD_TRACE` | `true`/`1` for verbose trace logging |

Building from Source

Requires [.NET 8 SDK](https://dotnet.microsoft.com/download/dotnet/8.0).

Chromium installs automatically on first run.

---

## Documentation

- [GDD-MANUAL.md](GDD-MANUAL.md) — Full usage manual with workflow examples
- [GDD-ARCHITECTURE.md](GDD-ARCHITECTURE.md) — Architecture deep-dive
- [GDD-PROMPT.md](GDD-PROMPT.md) — Claude agent instructions for MCP integration
- [DEPLOY-RAILWAY.md](DEPLOY-RAILWAY.md) — Host GDD as a remote MCP server on Railway (behind a token-auth proxy)
- [CONTRIBUTING.md](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](mailto: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](LICENSE) for full terms.

Commercial licensing: **[2vsmirnov@gmail.com](mailto:2vsmirnov@gmail.com)**