Local-First Chrome DevTools CLI for AI Agents
Direct CDP access for AI agents. No middleware, no servers, sub-ms local response.
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 connectsThe 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.
| 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 |
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:
- Ask the agent to install DOMGuard from
https://github.com/Guard8-ai/DOMGuard - Tag the guide file
@AGENTIC_AI_DOMGUARD_GUIDE.mdwhen you need browser automation - 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 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 directlygit clone https://github.com/Guard8-ai/DOMGuard.git
cd DOMGuard
cargo install --path .This installs to ~/.cargo/bin/ which is automatically in your PATH.
# 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# 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# 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# 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
# 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># 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"# 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# 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# 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"# 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# 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| 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
┌─────────────────┐ ┌─────────────────┐
│ 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
# Human-readable (default)
domguard debug dom
# JSON for programmatic use
domguard --json debug dom
domguard --json interact screenshot# 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 defaultdomguard [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- 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.
DOMGuard is designed for AI agent integration. See AGENTIC_AI_DOMGUARD_GUIDE.md for the complete quick reference.
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| 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 |
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.
git clone https://github.com/Guard8-ai/DOMGuard.git
cd DOMGuard
cargo build --release
# Binary at target/release/domguard- Rust 1.70+
- Chrome/Chromium with
--remote-debugging-port=9222
Yes, DOMGuard works great in Docker! It's just a CLI - connect Chrome and go.
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"]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# Start headless Chrome
docker run -d -p 9222:9222 browserless/chrome
# Run DOMGuard commands
domguard --host localhost --port 9222 debug domDOMGuard 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)| 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 |
# Connect to Browserless cloud
domguard --host chrome.browserless.io --port 443 \
--allow-remote debug dom# 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"# Throttle to avoid detection
domguard interact throttle-network --latency 100 --download 1000
# Add human-like delays
sleep 2
domguard interact click ".next"#!/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#!/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"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"])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));#!/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#!/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# .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"# 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}'MIT License - see LICENSE
Contributions welcome! See CONTRIBUTING.md for guidelines.
|
Grounded Progressive Architecture
Design methodology |
TaskGuard
Task management |
DOMGuard was designed using Grounded Progressive Architecture (GPA) - a six-phase methodology that keeps AI focused while preserving human vision and decision authority:
- Vision Casting - Concrete solution sketch, not abstract goals
- Iterative Deepening - Refine through structured cycles
- Stress Testing - Identify problems without immediate fixes
- Philosophical Grounding - "Local-first, privacy-first, any LLM" principles
- Boundary Setting - Decisive cuts based on philosophy
- Meta Review - Process improvement
Result: Complete architecture in 7 prompts. Zero scope drift.
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.
