Gdd 100/100 — SaferSkills

Is Gdd safe to install?

SaferSkills independently audited Gdd (Agent Skill) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.

CategoryWeightCategory scoreContribution

Securityprompt, exec, net, exfil, eval

35%

100

35.0 pts

Supply chainhash, typosquat, maintainer, lockfile

20%

100

20.0 pts

Maintenancestaleness, pinning, CI

15%

100

15.0 pts

TransparencySKILL.md, perms, README

15%

100

15.0 pts

Communityinstalls, verify, response

15%

100

15.0 pts

Findings & checks · 0 flagged

Securityscore 100 · 0 findings

✓—All security checks passedNo findings in this category for the latest scan.pass

Supply chainscore 100 · 0 findings

✓—All supply chain checks passedNo findings in this category for the latest scan.pass

Maintenancescore 100 · 0 findings

✓—All maintenance checks passedNo findings in this category for the latest scan.pass

Transparencyscore 100 · 0 findings

✓—All transparency checks passedNo findings in this category for the latest scan.pass

Communityscore 100 · 0 findings

✓—All community checks passedNo findings in this category for the latest scan.pass

The primary manifest — the file an agent reads to learn what this artifact does.

README.md · 1 file

README.md25.3 KB · Markdown

<h1 align="center">GDD — Giggly-Dazzling-Duckling</h1>

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:

Platform	Download	Run
Linux	GDD-Server-Linux.tar.gz	`chmod +x GDD.Headless && ./GDD.Headless`
macOS ARM	GDD-Server-macOS-ARM.tar.gz	`bash Scripts/setup-macos.sh && ./GDD.Headless`
macOS Intel	GDD-Server-macOS-Intel.tar.gz	`bash Scripts/setup-macos.sh && ./GDD.Headless`
Windows	GDD-Server-Windows.zip	`.\GDD.Headless.exe`
Docker	`ghcr.io/cap-of-tea/gdd`	`docker run -p 9700:9700 ghcr.io/cap-of-tea/gdd`
Claude Desktop	Win / Mac ARM / Mac Intel (.mcpb)	Open `.mcpb` file — installs as desktop extension

Desktop app (GUI) — a live grid of browser thumbnails you can click into:

Platform	Download	Run
Windows	GDD-Desktop-Windows.zip	Extract, run `GDD.exe` (WebView2 required)
Linux	GDD-Desktop-Linux.tar.gz	`bash Scripts/install-deps.sh && ./GDD.Desktop`
macOS ARM	GDD-Desktop-macOS-ARM.tar.gz	`bash Scripts/setup-macos.sh && ./GDD.Desktop`
macOS Intel	GDD-Desktop-macOS-Intel.tar.gz	`bash Scripts/setup-macos.sh && ./GDD.Desktop`

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

<details> <summary>Docker</summary>

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

</details>

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.

<details> <summary>Config file locations</summary>

Client	Project config	Global config
Claude Code	`<project>/.mcp.json`	`~/.claude/.mcp.json`
Cursor	`<project>/.cursor/mcp.json`	`~/.cursor/mcp.json`
VS Code / Windsurf / Antigravity	`<project>/.vscode/mcp.json`	IDE `settings.json`

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

</details>

<details> <summary>VS Code-based IDEs (Windsurf, Antigravity, Copilot)</summary>

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"]
    }
  }
}

</details>

<details> <summary>Permissions (Claude Code)</summary>

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.

</details>

<details> <summary>Auto-launch via stdio proxy (alternative)</summary>

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.

</details>

<details> <summary>Autostart as service (macOS / Linux)</summary>

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

</details>

<details> <summary>Direct HTTP (without AI client)</summary>

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.

</details>

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

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

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 `<select>` 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)

<details> <summary>Device Presets (22)</summary>

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

</details>

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.

	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

<details> <summary>Project Structure</summary>

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)

</details>

<details> <summary>Configuration</summary>

appsettings.json next to the executable:

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

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_PLAYER_IDLE_TIMEOUT_MINUTES`	Headless server only. Auto-remove a player untouched for this many minutes, reclaiming its browser. Default `30`; set `0` to disable. Prevents memory piling up when remote clients disconnect without removing their players
`GDD_TRACE`	`true`/`1` for verbose trace logging

</details>

<details> <summary>Building from Source</summary>

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.

</details>

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

<details> <summary>Privacy Policy</summary>

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: [[email protected]](mailto:[email protected])

</details>

License

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]](mailto:[email protected])

Gdd— agent skill

Is Gdd safe to install?

How It Works

Install

Connect to Your AI Client

Features

MCP Tools (39)

Player Management

Navigation

Interaction

Reading & Screenshots

Emulation

State & Diagnostics

Auth & Execution

Browser Storage

Help & Updates

Phones (11)

Tablets (6)

Desktops (5)

Architecture

Editions

Tech Stack

Command-line flags

Environment variables

Documentation

Privacy

License

Audit the pieces. Scan the whole. Decide.