Skip to content

Guard8-ai/DOMGuard

Repository files navigation

DOMGuard

DOMGuard Logo

CI Release Documentation License: MIT Rust

Local-First Chrome DevTools CLI for AI Agents

Direct CDP access for AI agents. No middleware, no servers, sub-ms local response.

Why Rust CLI over MCP?

At Guard8.ai, we build Rust CLI tools instead of MCP servers. Here's why:

Aspect Rust CLI MCP Servers Python/Node CLI
Universality Any LLM/agent MCP-compatible only Any LLM/agent
Dependencies Zero Runtime + protocol Python/Node runtime
Installation Copy binary Server setup pip install, version conflicts
Startup time Instant (<10ms) Server initialization Runtime startup
Portability Single binary Config + dependencies Virtual envs, node_modules
Debugging Run manually MCP inspector Run manually

Zero friction deployment:

# Rust CLI - just works
curl -L .../domguard -o domguard && chmod +x domguard
./domguard status

# Python - friction
python -m venv .venv && source .venv/bin/activate
pip install domguard  # hope dependencies resolve
domguard status

# MCP - more friction
npm install @anthropic/mcp-server-domguard
# configure claude_desktop_config.json
# restart Claude Desktop
# hope it connects

The insight: Every AI coding agent can execute shell commands. A single Rust binary means zero runtime dependencies, instant startup, and no version conflicts.

Rust CLI is the universal, zero-friction interface for AI agents.

Why DOMGuard?

Feature DOMGuard Playwright MCP Chrome DevTools MCP Project Mariner OpenAI Operator
Architecture Local CLI MCP Server MCP Server Cloud VM Cloud VM
Latency Sub-ms Network RTT Network RTT High (cloud) High (cloud)
Privacy 100% local Server-dependent Server-dependent Cloud processing Cloud processing
Cost Free Free Free $249.99/mo ChatGPT Pro
Offline Yes No No No No
AI Integration Any LLM Claude only Claude/Cursor Gemini only GPT-4o only
Open Source Yes Yes Yes No No

Quick Start

Use with Any AI Coding Agent

DOMGuard works with any AI coding agent that runs in a VM environment - Claude Code (web), Cursor, Windsurf, GitHub Copilot Workspace, and more.

Zero memorization workflow:

  1. Ask the agent to install DOMGuard from https://github.com/Guard8-ai/DOMGuard
  2. Tag the guide file @AGENTIC_AI_DOMGUARD_GUIDE.md when you need browser automation
  3. Ask your questions naturally - the agent reads the guide and executes commands
You: @AGENTIC_AI_DOMGUARD_GUIDE.md take a screenshot of the current page
You: @AGENTIC_AI_DOMGUARD_GUIDE.md click the login button and fill the form
You: @AGENTIC_AI_DOMGUARD_GUIDE.md extract the design system from stripe.com

No need to memorize commands. The guide has everything the agent needs.

Download Pre-built Binary

Download the latest release for your platform from GitHub Releases:

Platform Binary
Linux x86_64 domguard-linux-x86_64
macOS ARM64 (Apple Silicon) domguard-macos-aarch64
Windows x86_64 domguard-windows-x86_64.exe
# Linux/macOS: Make executable and move to PATH
chmod +x domguard-*
sudo mv domguard-* /usr/local/bin/domguard

# Windows: Add to PATH or run directly

Install from Source

git clone https://github.com/Guard8-ai/DOMGuard.git
cd DOMGuard
cargo install --path .

This installs to ~/.cargo/bin/ which is automatically in your PATH.

Get Started

# Initialize in your project
domguard init

# Start Chrome with debugging enabled
chrome --remote-debugging-port=9222

# Check connection
domguard status

# Try it out
domguard debug dom
domguard interact click "button.submit"
domguard inspire https://example.com

Features

Debug Mode - Inspect Page State

# DOM inspection
domguard debug dom                          # Full DOM tree
domguard debug dom "div.container"          # Specific element

# Styles
domguard debug styles "button.primary"      # Computed styles

# Console
domguard debug console                      # View messages
domguard debug console --follow             # Stream live
domguard debug console --filter "error"     # Filter messages

# Network
domguard debug network                      # All requests
domguard debug network --filter "api"       # Filter by URL

# JavaScript
domguard debug eval "document.title"        # Execute JS

# Storage
domguard debug storage                      # localStorage/sessionStorage
domguard debug cookies                      # View cookies

# Accessibility
domguard debug aria                         # Full ARIA tree
domguard debug aria "nav"                   # Specific element

# Tab Management
domguard debug tabs list                    # List all tabs
domguard debug tabs new "https://example.com"  # Create tab
domguard debug tabs switch <tab-id>         # Switch to tab
domguard debug tabs close <tab-id>          # Close tab

Interact Mode - Control Browser

# Mouse Actions
domguard interact click "button.submit"           # Click element
domguard interact click --coords 100,200          # Click coordinates
domguard interact hover "div.menu"                # Hover element
domguard interact drag --from "#source" --to "#target"  # Drag and drop

# Keyboard
domguard interact type "input.search" "hello"     # Type text
domguard interact type --focused "hello world"    # Type to focused
domguard interact key "Enter"                     # Press key
domguard interact key "ctrl+a ctrl+c"             # Key sequence

# Forms
domguard interact select "select#country" "US"              # By value
domguard interact select "select#country" "United States" --by-label
domguard interact upload "input[type=file]" ./doc.pdf       # File upload

# Navigation
domguard interact navigate "https://example.com"  # Go to URL
domguard interact back                            # Go back
domguard interact refresh                         # Refresh page
domguard interact scroll --down 500               # Scroll pixels
domguard interact scroll --to "footer"            # Scroll to element

# Screenshots & PDF
domguard interact screenshot                      # Viewport
domguard interact screenshot --full               # Full page
domguard interact screenshot --element "div.hero" # Element
domguard interact pdf -o page.pdf                 # Export PDF
domguard interact pdf --landscape                 # Landscape PDF

# Dialogs
domguard interact dialog --accept                 # Accept alert
domguard interact dialog --accept --text "yes"    # Prompt response

# Viewport
domguard interact resize 1920 1080                # Resize viewport

# Wait Conditions
domguard interact wait "div.loaded"               # Wait for element
domguard interact wait "div.spinner" --gone       # Wait until gone
domguard interact wait --text "Success"           # Wait for text
domguard interact wait --text-gone "Loading..."   # Wait text gone

# Advanced Mouse Control (Anthropic Computer Use)
domguard interact mouse-move 100,200              # Move cursor without click
domguard interact cursor-position                 # Get current cursor coords
domguard interact triple-click "p.content"        # Select paragraph
domguard interact triple-click --coords 100,200   # Triple-click at coords
domguard interact mouse-down left                 # Press mouse button
domguard interact mouse-up left                   # Release mouse button

# Advanced Keyboard (Anthropic Computer Use)
domguard interact hold-key Shift --duration 1000  # Hold key for 1 second

# Screenshot Region (zoom/crop)
domguard interact screenshot-region 0,0,800,600   # Capture region x,y,w,h
domguard interact screenshot-region 100,100,400,300 -o crop.png

# Wait Duration
domguard interact wait-duration 2000              # Wait 2 seconds

Inspire Mode - Extract Design Patterns

# Extract design system from any website
domguard inspire https://stripe.com

# Focus on specific component
domguard inspire https://stripe.com --component "nav.header"

# Save for later reference
domguard inspire https://stripe.com --save "stripe-nav"

Extracts:

  • Color palette with usage frequency
  • Typography (fonts, sizes, weights, line-heights)
  • Spacing system (padding, margin, gap values)
  • Layout patterns (flex/grid usage)
  • Animation timing functions

Session Recording - Capture Action History

# Start recording actions
domguard session start                    # Begin new session
domguard session start --name "checkout"  # Named session

# Check recording status
domguard session status                   # Show current session info

# Stop and save recording
domguard session stop                     # Stop current session

# List recorded sessions
domguard session list                     # Show all sessions

# View session details
domguard session show <session-id>        # Detailed action log

# Export session
domguard session export <session-id> -o session.json

# Delete session
domguard session delete <session-id>

Workflow Mode - Reusable Automation

# Create workflow from recorded session
domguard workflow create "login-flow" --from-session <session-id>

# Create workflow from YAML file
domguard workflow create "checkout" --file workflow.yaml

# List all workflows
domguard workflow list

# Run a workflow
domguard workflow run "login-flow"
domguard workflow run "login-flow" --dry-run    # Preview without executing

# View workflow details
domguard workflow show "login-flow"

# Delete workflow
domguard workflow delete "login-flow"

User Takeover - Human-in-the-Loop

# Request human takeover (pauses automation)
domguard takeover request                 # Pause for human intervention
domguard takeover request --reason "CAPTCHA detected"

# Check takeover status
domguard takeover status

# Signal completion (resume automation)
domguard takeover done

Self-Correction - Automatic Error Recovery

# Configure correction behavior
domguard correction config --max-retries 3
domguard correction config --strategy "adaptive"

# View correction settings
domguard correction config --show

# Analyze page for potential issues
domguard correction analyze

# Manual retry with correction
domguard correction retry

Site Instructions - Per-Site Behaviors

# Create site-specific instructions
domguard sites create "example.com" --instructions "Always click cookie accept"

# List configured sites
domguard sites list

# View site instructions
domguard sites show "example.com"

# Update instructions
domguard sites update "example.com" --instructions "New behavior"

# Delete site config
domguard sites delete "example.com"

# Block a site
domguard sites block "malicious-site.com"
domguard sites unblock "malicious-site.com"

Security Commands - Safety Features

# Check page for security concerns
domguard security check                   # Full security scan
domguard security check --captcha         # CAPTCHA detection only
domguard security check --sensitive       # Sensitive field detection

# Block/unblock sites
domguard security block "phishing-site.com"
domguard security unblock "safe-site.com"
domguard security blocked                 # List blocked sites

# Credential masking
domguard security mask --enable           # Enable credential masking
domguard security mask --disable          # Disable masking

Performance & Throttling

# Get performance metrics
domguard debug performance                # Core Web Vitals, timing

# CPU throttling
domguard debug throttle-cpu 4             # 4x slowdown
domguard debug throttle-cpu --disable     # Disable throttling

# Network throttling
domguard debug throttle-network slow-3g   # Slow 3G preset
domguard debug throttle-network 3g        # Regular 3G
domguard debug throttle-network offline   # Offline mode
domguard debug throttle-network --disable # Disable throttling

# DOM snapshot export
domguard debug snapshot -o page.html      # Export full DOM

Feature Comparison

Capability DOMGuard Playwright MCP DevTools MCP Mariner Operator
Architecture Local CLI MCP Server MCP Server Cloud Cloud
Cost Free Free Free $250/mo Pro
Privacy Full Partial Partial Cloud Cloud
Any LLM
Open Source
Offline
Click/Type/Navigate
Screenshots
Screenshot Region
PDF Export
Tab Management ~
DOM Inspection
ARIA/Accessibility
Console Messages
Network Monitoring
Performance Metrics
CPU/Network Throttling
Triple-click
Mouse Down/Up
Hold Key
Session Recording
Reusable Workflows
Self-correction
User Takeover
CAPTCHA Detection
Per-site Instructions
Blocked Sites
Design Extraction

✓ = supported, ~ = limited

Architecture

┌─────────────────┐     ┌─────────────────┐
│   AI Agent      │     │     Chrome      │
│  (Any LLM)      │     │   Browser       │
└────────┬────────┘     └────────┬────────┘
         │                       │
         │ CLI calls             │ CDP WebSocket
         │                       │ (localhost:9222)
         ▼                       │
┌─────────────────┐              │
│    DOMGuard     │◄─────────────┘
│   (Local CLI)   │
└─────────────────┘

Key Benefits:

  • Zero latency: Direct CDP connection, no middleware
  • Full privacy: Everything runs locally
  • Any LLM: Not locked to specific AI provider
  • Offline capable: Works without internet
  • Simple integration: Just shell commands

Output Formats

# Human-readable (default)
domguard debug dom

# JSON for programmatic use
domguard --json debug dom
domguard --json interact screenshot

Configuration

# Initialize creates .domguard/config.toml
domguard init
# .domguard/config.toml
[chrome]
host = "127.0.0.1"
port = 9222

[defaults]
timeout_ms = 30000
screenshot_format = "png"

[security]
allow_remote = false  # Only localhost by default

CLI Options

domguard [OPTIONS] <COMMAND>

Options:
  --json               Output in JSON format
  --host <HOST>        Chrome DevTools host (default: 127.0.0.1)
  --port <PORT>        Chrome DevTools port (default: 9222)
  --timeout <TIMEOUT>  Command timeout in milliseconds
  -h, --help           Print help
  -V, --version        Print version

Commands:
  init       Initialize DOMGuard in current directory
  status     Check Chrome connection status
  inspire    Extract design patterns from websites
  debug      Inspect page state (DOM, console, network, storage, performance)
  interact   Control browser (click, type, navigate, screenshot)
  session    Record and manage browser sessions
  workflow   Create and run reusable automation workflows
  takeover   Human-in-the-loop control handoff
  correction Self-correction and error recovery settings
  sites      Per-site instructions and blocked sites
  security   Security checks, CAPTCHA detection, credential masking

Security

  • Localhost only by default: Won't connect to remote Chrome instances
  • Credential masking: Sensitive data (tokens, passwords) masked in output
  • No data collection: Everything stays on your machine
  • Open source: Full code transparency
  • CAPTCHA detection: Warns before automating CAPTCHA-protected pages
  • Blocked sites: Configure sites that should never be automated

See SECURITY.md for the full security policy, remote connection setup, and vulnerability reporting.

For AI Agents

DOMGuard is designed for AI agent integration. See AGENTIC_AI_DOMGUARD_GUIDE.md for the complete quick reference.

System Prompt Example

You have access to DOMGuard for browser automation via shell commands.

## Core Commands
- `domguard status` - Check Chrome connection
- `domguard debug dom [selector]` - Inspect DOM tree
- `domguard debug aria` - Get accessibility tree (useful for understanding page structure)
- `domguard interact click "<selector>"` - Click element
- `domguard interact type "<selector>" "<text>"` - Type text
- `domguard interact screenshot` - Take screenshot
- `domguard interact wait "<selector>"` - Wait for element
- `domguard --json <command>` - Get JSON output for parsing

## Advanced Commands
- `domguard interact mouse-move <x>,<y>` - Move cursor without clicking
- `domguard interact triple-click "<selector>"` - Select paragraph
- `domguard interact screenshot-region <x>,<y>,<w>,<h>` - Capture region
- `domguard interact hold-key <key> --duration <ms>` - Hold key
- `domguard debug tabs list` - List browser tabs

## Session & Workflow Commands
- `domguard session start` - Start recording actions
- `domguard session stop` - Stop and save recording
- `domguard workflow run "<name>"` - Execute saved workflow
- `domguard takeover request --reason "<reason>"` - Request human intervention

## Safety Commands
- `domguard security check` - Check for CAPTCHAs, sensitive fields
- `domguard security check --captcha` - CAPTCHA detection only
- `domguard correction analyze` - Analyze page for potential issues

## Best Practices
1. Always check `domguard status` before automation
2. Use `--json` for programmatic parsing
3. Use `debug aria` to understand page structure for accessibility
4. Use `wait` commands before interacting with dynamic elements
5. Use `screenshot` to verify visual state when needed
6. Use `security check` before interacting with login/payment forms
7. Use `takeover request` when encountering CAPTCHAs or complex interactions

Complete Command Reference

Category Command Description
Setup init, status Initialize and check connection
Inspect debug dom, debug aria, debug console, debug network Page inspection
Navigate interact navigate, back, refresh Browser navigation
Click interact click, hover, triple-click Mouse clicks
Type interact type, key, hold-key Keyboard input
Wait interact wait, wait-duration Synchronization
Forms interact select, upload, dialog Form interaction
Capture interact screenshot, screenshot-region, pdf Page capture
Advanced mouse-move, mouse-down, mouse-up, cursor-position Precise control
Tabs debug tabs list/new/switch/close Tab management
Design inspire Extract design patterns
Recording session start/stop/status/list/show/export Session recording
Workflows workflow create/list/run/show/delete Reusable automation
Takeover takeover request/status/done Human-in-the-loop
Correction correction config/analyze/retry Error recovery
Sites sites create/list/show/update/delete/block Per-site config
Security security check/block/unblock/blocked/mask Safety features
Performance debug performance, throttle-cpu, throttle-network Performance testing

Installation

From Source (Global Install)

git clone https://github.com/Guard8-ai/DOMGuard.git
cd DOMGuard
cargo install --path .

This installs to ~/.cargo/bin/ which is automatically in your PATH.

From Source (Local Build)

git clone https://github.com/Guard8-ai/DOMGuard.git
cd DOMGuard
cargo build --release
# Binary at target/release/domguard

Requirements

  • Rust 1.70+
  • Chrome/Chromium with --remote-debugging-port=9222

Docker Deployment

Yes, DOMGuard works great in Docker! It's just a CLI - connect Chrome and go.

Dockerfile

FROM rust:1.75-slim as builder
WORKDIR /app
RUN apt-get update && apt-get install -y pkg-config libssl-dev
COPY . .
RUN cargo build --release

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y \
    chromium \
    chromium-sandbox \
    && rm -rf /var/lib/apt/lists/*

COPY --from=builder /app/target/release/domguard /usr/local/bin/

# Start Chrome with remote debugging
ENV CHROME_BIN=/usr/bin/chromium
ENTRYPOINT ["domguard"]

docker-compose.yml

version: '3.8'
services:
  chrome:
    image: browserless/chrome:latest
    ports:
      - "9222:9222"
    environment:
      - CONNECTION_TIMEOUT=600000

  domguard:
    build: .
    depends_on:
      - chrome
    environment:
      - DOMGUARD_HOST=chrome
      - DOMGUARD_PORT=9222
    volumes:
      - ./screenshots:/app/screenshots

Quick Docker Run

# Start headless Chrome
docker run -d -p 9222:9222 browserless/chrome

# Run DOMGuard commands
domguard --host localhost --port 9222 debug dom

Serverless & Cloud

AWS Lambda / Google Cloud Functions

DOMGuard is a stateless CLI - perfect for serverless:

# lambda_function.py
import subprocess
import json

def handler(event, context):
    # Chrome runs separately (Browserless, or Chrome in another container)
    cmd = ["domguard", "--json", "--host", "chrome.internal", "debug", "dom"]
    result = subprocess.run(cmd, capture_output=True, text=True)
    return json.loads(result.stdout)

Recommended Cloud Architectures

Architecture Use Case Cost
Lambda + Browserless Occasional scraping Pay per use
ECS/Fargate + Chrome Continuous automation ~$30/mo
EC2 + Chrome High volume ~$50/mo
Kubernetes + Chrome pool Enterprise scale Variable

Browserless.io Integration

# Connect to Browserless cloud
domguard --host chrome.browserless.io --port 443 \
         --allow-remote debug dom

Production Scraping

Best Practices

# 1. Use JSON output for parsing
domguard --json debug dom "#products" | jq '.elements[].text'

# 2. Add waits for dynamic content
domguard interact wait "[data-loaded='true']" --timeout 10000
domguard --json debug dom ".product-card"

# 3. Handle pagination
for page in $(seq 1 10); do
  domguard interact click ".next-page"
  domguard interact wait ".products-loaded"
  domguard --json debug dom ".product" >> products.jsonl
done

# 4. Screenshot on error for debugging
domguard interact screenshot --output "debug_$(date +%s).png"

Rate Limiting

# Throttle to avoid detection
domguard interact throttle-network --latency 100 --download 1000

# Add human-like delays
sleep 2
domguard interact click ".next"

Error Recovery

#!/bin/bash
# retry_scrape.sh
MAX_RETRIES=3
for i in $(seq 1 $MAX_RETRIES); do
  if domguard --json debug dom ".data" > output.json 2>/dev/null; then
    exit 0
  fi
  echo "Retry $i/$MAX_RETRIES..."
  sleep $((i * 2))
done
exit 1

Scripting & Automation

Bash Scripting

#!/bin/bash
# scrape_prices.sh

URL="https://example.com/products"
domguard interact navigate "$URL"
domguard interact wait ".price"

# Extract all prices
domguard --json debug dom ".price" | \
  jq -r '.elements[].text' | \
  sed 's/[^0-9.]//g' > prices.txt

echo "Found $(wc -l < prices.txt) prices"

Python Integration

import subprocess
import json

def domguard(command: str) -> dict:
    """Run DOMGuard command and return JSON result."""
    result = subprocess.run(
        f"domguard --json {command}",
        shell=True, capture_output=True, text=True
    )
    return json.loads(result.stdout) if result.stdout else {}

# Usage
domguard("interact navigate 'https://example.com'")
domguard("interact wait '.content'")
data = domguard("debug dom '.product'")

for element in data.get("elements", []):
    print(element["text"])

Node.js Integration

const { execSync } = require('child_process');

function domguard(command) {
  const result = execSync(`domguard --json ${command}`, { encoding: 'utf8' });
  return JSON.parse(result);
}

// Usage
domguard(`interact navigate "https://example.com"`);
domguard(`interact wait ".loaded"`);
const { elements } = domguard(`debug dom ".item"`);
elements.forEach(el => console.log(el.text));

QA & Testing

Visual Regression Testing

#!/bin/bash
# visual_regression.sh

# Take baseline screenshot
domguard interact navigate "$TEST_URL"
domguard interact wait ".app-loaded"
domguard interact screenshot --output "baseline.png"

# Deploy new version...

# Take comparison screenshot
domguard interact navigate "$TEST_URL"
domguard interact wait ".app-loaded"
domguard interact screenshot --output "current.png"

# Compare with ImageMagick
compare -metric AE baseline.png current.png diff.png 2>&1

E2E Test Example

#!/bin/bash
# test_login.sh
set -e

echo "Testing login flow..."

# Navigate to login
domguard interact navigate "https://app.example.com/login"
domguard interact wait "#email"

# Fill form
domguard interact type "#email" "test@example.com"
domguard interact type "#password" "testpass123"
domguard interact click "#submit"

# Verify redirect
domguard interact wait ".dashboard"
TITLE=$(domguard --json debug dom "h1" | jq -r '.elements[0].text')

if [[ "$TITLE" == "Welcome" ]]; then
  echo "✅ Login test passed"
  exit 0
else
  echo "❌ Login test failed: Expected 'Welcome', got '$TITLE'"
  domguard interact screenshot --output "test_failure.png"
  exit 1
fi

CI/CD Integration

# .github/workflows/e2e.yml
name: E2E Tests
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      chrome:
        image: browserless/chrome
        ports:
          - 9222:9222

    steps:
      - uses: actions/checkout@v4

      - name: Install DOMGuard
        run: cargo install --path .

      - name: Run E2E tests
        run: |
          domguard --host localhost status
          ./tests/e2e/run_all.sh

      - name: Upload screenshots on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: failure-screenshots
          path: "*.png"

Accessibility Testing

# Get accessibility tree for WCAG compliance
domguard debug aria > accessibility.txt

# Check for missing alt text
domguard --json debug dom "img:not([alt])" | \
  jq '.count' | \
  xargs -I {} test {} -eq 0 || echo "Missing alt text!"

# Check heading hierarchy
domguard --json debug dom "h1,h2,h3,h4,h5,h6" | \
  jq -r '.elements[].tag' | \
  awk 'NR>1 && $1-prev>1 {print "Skipped heading level at line " NR} {prev=$1}'

License

MIT License - see LICENSE

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

Built With

Grounded Progressive Architecture
Design methodology
TaskGuard
Task management

Designed with GPA

DOMGuard was designed using Grounded Progressive Architecture (GPA) - a six-phase methodology that keeps AI focused while preserving human vision and decision authority:

  1. Vision Casting - Concrete solution sketch, not abstract goals
  2. Iterative Deepening - Refine through structured cycles
  3. Stress Testing - Identify problems without immediate fixes
  4. Philosophical Grounding - "Local-first, privacy-first, any LLM" principles
  5. Boundary Setting - Decisive cuts based on philosophy
  6. Meta Review - Process improvement

Result: Complete architecture in 7 prompts. Zero scope drift.

Built with TaskGuard

Development managed with TaskGuard - AI-native task management with causality tracking. 84 tasks completed in 2 days.


DOMGuard - Local-first browser automation for AI agents.

About

Local-First Chrome DevTools CLI for AI Agents

Resources

License

Contributing

Security policy

Stars

Watchers

Forks

Packages

No packages published

Contributors 2

  •  
  •