setup

name	setup
description	Interactive setup wizard for agent-browser automation. Use when the user says "set up browser automation", "set up squiz", "install agent-browser", "install squiz", "configure browser testing", "configure squiz", or asks how to get the squiz skill working. Also trigger if the squiz skill fails because agent-browser is not installed. This skill interviews the user about their environment and configures everything needed for the squiz skill to work.
disable-model-invocation	true
tools	Bash, Read, Write, Edit

Browser Automation Setup Wizard

You are a setup assistant for the agent-browser skill. Walk the user through installation and configuration interactively. Use AskUserQuestion to gather input at each stage rather than asking open-ended questions.

Stage 1: Environment Detection

Before asking the user anything, silently detect what you can:

# Check OS
uname -a 2>/dev/null || echo "WINDOWS"

# Check if agent-browser is already installed
command -v agent-browser 2>/dev/null && agent-browser --version

# Check if Chrome for Testing is installed
agent-browser install --check 2>/dev/null

# Check if npm is available
npm --version 2>/dev/null

# Check if running in WSL
grep -qi microsoft /proc/version 2>/dev/null && echo "WSL_DETECTED"

# Check if Claude Code permissions already allow agent-browser
cat .claude/settings.json 2>/dev/null
cat .claude/settings.local.json 2>/dev/null
cat ~/.claude/settings.json 2>/dev/null

# Check for existing Edge/Chrome with debugging
pgrep -f "remote-debugging-port" 2>/dev/null

Report what you found, then proceed to the interview.

Stage 2: User Interview

Ask these questions using AskUserQuestion. Collect all answers before taking action.

Question 1: Environment

Ask the user which environment they're setting up for:

• Remote Linux VM (headless, SSH access, e.g. Azure/AWS/Hetzner)
• Windows 11 native (Claude Code via Git Bash or PowerShell)
• WSL 2 on Windows (Ubuntu/Debian under Windows)
• macOS

Question 2: Browser Strategy

Based on their environment, ask how they want to use the browser:

If Remote VM:

• Headless only (agent-browser manages its own Chrome — simplest)
• Connect to remote Chrome (already running Chrome with CDP on this machine)

If Windows native:

• Headless only (agent-browser manages its own Chrome)
• Connect to Edge (auto-connect to running Edge for login state reuse)
• Both (headless by default, Edge when auth is needed)

If WSL:

• Headless in WSL (agent-browser manages its own Chrome inside WSL)
• Bridge to Windows Edge (connect to Edge via debugging port across WSL boundary)

If macOS:

• Headless only (agent-browser manages its own Chrome)
• Connect to Chrome (auto-connect to running Chrome)

Question 3: Defaults

Ask which optional defaults they want enabled:

• Auto-connect to running browser (sets AGENT_BROWSER_AUTO_CONNECT=1)
• Headed mode by default (sets AGENT_BROWSER_HEADED=1 — see browser window)
• Dark mode (sets AGENT_BROWSER_COLOR_SCHEME=dark)
• Idle timeout (auto-shutdown daemon after inactivity — recommended for VMs)
• None of these (pure defaults, configure per-invocation)

Question 4: Claude Code Permissions

Ask whether to configure Claude Code permissions:

• Yes — project-level (writes to .claude/settings.local.json in current project)
• Yes — user-level (writes to ~/.claude/settings.json for all projects)
• No — I'll handle permissions myself

Stage 3: Installation

Based on the answers, execute the appropriate steps. Show the user what you're doing at each step.

3a: Install agent-browser

# Check if already installed
if command -v agent-browser &>/dev/null; then
  echo "agent-browser already installed: $(agent-browser --version)"
  echo "Upgrading to latest..."
  agent-browser upgrade
else
  npm install -g agent-browser
fi

3b: Install Chrome for Testing

# Linux VM with system deps
agent-browser install --with-deps

# All other platforms
agent-browser install

Windows: If Defender blocks the binary, tell the user:

Windows Defender may flag agent-browser as a false positive (Trojan:Script/Wacatac.C!ml). The binary is not code-signed yet. You'll need to add an exclusion in Windows Security → Virus & threat protection → Exclusions for your global npm directory.

3c: Configure Environment Variables

If the user selected any defaults in Question 3, add them to their shell profile.

Detect the shell first:

echo $SHELL
basename "$SHELL"

Then append to the appropriate file (~/.bashrc, ~/.zshrc, or ~/.profile):

# agent-browser defaults
export AGENT_BROWSER_AUTO_CONNECT=1        # if selected
export AGENT_BROWSER_HEADED=1              # if selected
export AGENT_BROWSER_COLOR_SCHEME=dark     # if selected
export AGENT_BROWSER_IDLE_TIMEOUT_MS=300000  # if selected (5 min)

Do not duplicate entries — check if the variable is already exported before adding.

3d: Configure Claude Code Permissions

If the user opted in, write the permission rule:

Project-level (.claude/settings.local.json):

mkdir -p .claude
# Read existing file, merge, or create new

User-level (~/.claude/settings.json):

# Read existing file, merge, or create new

The permission block to merge:

{
  "permissions": {
    "allow": [
      "Bash(agent-browser *)"
    ]
  }
}

Important: If the file already exists, read it first and merge the allow rule into the existing permissions.allow array. Never overwrite existing settings.

3e: Windows Edge Auto-Connect Setup

If the user selected Edge auto-connect on Windows, offer to create a shortcut:

To use auto-connect, Edge needs to be launched with --remote-debugging-port=9222. The easiest approach is to modify your Edge shortcut or create a new one.

Add this to the shortcut target: "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222

Alternatively, you can launch Edge from the terminal when you need it:

& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222

3f: WSL Bridge Setup

If the user selected the WSL-to-Windows bridge:

Launch Edge on Windows with debugging enabled:

& "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe" --remote-debugging-port=9222

Then from WSL, connect via the port (accessible across the WSL boundary):

agent-browser --port 9222 open https://example.com

Stage 4: Verification

Run a quick smoke test to confirm everything works:

agent-browser open https://example.com
agent-browser snapshot -i
agent-browser screenshot /tmp/squiz-test.png
agent-browser close

If this succeeds, report:

✓ agent-browser installed and working ✓ Chrome for Testing available ✓ [permissions configured / env vars set — as applicable]

The squiz skill is ready to use. It will trigger automatically when you ask to check a web page, test a deployment, debug frontend issues, or perform any browser-based task.

If it fails, read the troubleshooting guide at ../squiz/references/troubleshooting.md and walk the user through the relevant fix.

Stage 5: Optional — Install Official Skill

Ask the user if they also want to install the upstream agent-browser skill from Vercel for additional context:

• Yes — runs npx skills add vercel-labs/agent-browser --skill agent-browser
• No — the squiz skill is sufficient on its own

Explain: The Vercel skill gives Claude Code richer context about the snapshot-interact workflow. It complements but doesn't replace the squiz skill, which adds context isolation, effort control, and the summary-only return pattern.