Agent browser

Agent Browser

Open a URL in the headless browser. Runs a health check first — if the browser is broken, errors out with a full diagnostic trace so the user can fix it.

Instructions

Step 1 — Parse arguments

Arguments received: $ARGUMENTS

• URL: $0 (required)
• VIEWPORT: value after --viewport flag if present. Default: desktop
• SESSION: value after --session flag if present (optional, for session isolation)

If URL is missing, ask the user to provide it.

Viewport defaults

Name	Width	Height
desktop	1920	1080
mobile	414	896

Default is desktop if --viewport is not specified.

Step 2 — Preflight health check

Run each check sequentially. If any check fails, stop immediately and report the full diagnostic trace to the user.

2a. Check agent-browser is installed

command -v agent-browser && agent-browser --version 2>&1 || echo "FAIL: agent-browser not found in PATH"

If not found, install it — use npm (not pnpm) and pin to 0.8.5:

sudo npm install -g [email protected]

Then install Chromium + system deps. agent-browser install --with-deps shells out to a playwright binary that isn't bundled with this package, so on a fresh image you'll also need the playwright CLI available:

agent-browser install --with-deps    # installs system libs (apt)
# If it ends with "sh: 1: playwright: not found":
sudo npm install -g playwright@latest
npx playwright install chromium

Verify:

agent-browser --version     # → agent-browser 0.8.5
agent-browser open about:blank && agent-browser close

Rationale for the pins:

• npm, not pnpm — PNPM_HOME is /usr/local/share/pnpm, owned by root; pnpm add -g as the sandbox user fails with EACCES.
• 0.8.5 — later majors have breaking CLI changes; the rest of this skill targets 0.8.5's flags.

Or rebuild the image with INSTALL_AGENT_BROWSER=true in .devcontainer/.env to bake this in.

After installing, resume the health check from step 2b — do not stop.

2b. Check Chromium launches

agent-browser open "about:blank" 2>&1

If this fails (non-zero exit, error output mentioning "chrome", "chromium", "ENOENT", "launch", or "sandbox"), report the full error and:

Chromium failed to launch. Common causes:

1. Missing system dependencies:
   apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 \
     libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 \
     libpango-1.0-0 libcairo2 libasound2 libxshmfence1 libx11-xcb1 \
     fonts-liberation xdg-utils

2. Chromium not downloaded:
   agent-browser install --with-deps

3. Sandbox permission issue (containers):
   Ensure --no-sandbox is set or container has SYS_ADMIN capability.

Stop here — do not continue. Close the failed session first:

agent-browser close 2>/dev/null

2c. Verify page loaded

agent-browser snapshot -c 2>&1

If snapshot returns content (even minimal), the browser is healthy. Close the health-check session:

agent-browser close

Step 2d — DNS resolution check (tunnel hostnames)

If the URL contains a hostname served by a tunnel or reverse proxy, the container's DNS may not resolve it yet. Check and fix:

HOSTNAME=$(echo "$URL" | sed 's|https\?://||; s|/.*||; s|:.*||')
if ! getent hosts "$HOSTNAME" &>/dev/null; then
  # Resolve via Cloudflare DNS API
  IP=$(curl -sf "https://cloudflare-dns.com/dns-query?name=${HOSTNAME}&type=A" \
    -H "accept: application/dns-json" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['Answer'][0]['data'])" 2>/dev/null)
  if [ -n "$IP" ]; then
    echo "$IP $HOSTNAME" | sudo tee -a /etc/hosts >/dev/null
    echo "Added $HOSTNAME -> $IP to /etc/hosts (container DNS didn't resolve it)"
  else
    echo "FAIL: $HOSTNAME does not resolve. Check tunnel/DNS routing."
    # Stop here
  fi
fi

This ensures agent-browser can reach tunnel-served sites even when the container's DNS resolver hasn't propagated the CNAME yet.

Step 3 — Open the target URL with viewport

Set the viewport size based on the selected viewport, then open the URL:

# Desktop: 1920x1080, Mobile: 375x812
agent-browser open "$URL" --viewport-width $WIDTH --viewport-height $HEIGHT $( [ -n "$SESSION" ] && echo "--session $SESSION" )

If agent-browser open does not support --viewport-width/--viewport-height flags, open the URL first, then resize:

agent-browser open "$URL" $( [ -n "$SESSION" ] && echo "--session $SESSION" )
agent-browser execute "await page.setViewportSize({ width: $WIDTH, height: $HEIGHT })"

If this fails, report the error with the full output.

Step 4 — Confirm page loaded and screenshot

agent-browser snapshot -c

Report a summary of what loaded (page title, key elements visible).

Take a screenshot to .claude/screenshots/ using a descriptive filename derived from the URL path:

# Generate filename from URL: strip protocol, replace / with --, remove trailing -
FILENAME=$(echo "$URL" | sed 's|https\?://||; s|/|--|g; s|--$||; s|[^a-zA-Z0-9._-]|-|g')
agent-browser screenshot ".claude/screenshots/${FILENAME}.png"

Example: https://my-app.oh-local.localhost:8443/guide/configuration/ → .claude/screenshots/my-app.oh-local.localhost-8443--guide--configuration.png

Step 5 — Report

Browser ready.

  URL:        $URL
  Viewport:   $VIEWPORT ($WIDTHx$HEIGHT)
  Session:    $SESSION (or "default")
  Screenshot: .claude/screenshots/$FILENAME.png

  Next steps:
    agent-browser screenshot <path>       # capture to custom path
    agent-browser snapshot -i             # interactive elements
    agent-browser is visible "<selector>" # wait for element
    agent-browser close                   # end session (always do this)

Session Hygiene

• ALWAYS close browser sessions when done: agent-browser close
• Use --session <name> for isolation between concurrent test runs
• If any step errors, close the session before reporting to the user