Browser Automation

Purpose

Reference playbook for web automation tasks. Provides layer selection, error recovery strategies, CSS selector patterns, form filling methodology, and safety gates. Loaded when Genesis performs browser-based tasks.

Browser Layers

Genesis has four layers of browser interaction. Choose the lightest layer that can accomplish the task. Token cost increases with each layer.

Layer 1: Web Fetch (read-only, public data — zero browser tokens)

• Tools: WebFetch, Firecrawl, genesis.web (SearXNG + Brave)
• Use for: public information retrieval, search, reading articles
• No authentication, no interaction, no JavaScript rendering
• Fastest and cheapest option

Layer 2: Genesis Browser Tools (persistent profile, on-demand)

• Tools: browser_navigate, browser_click, browser_fill, browser_upload, browser_press_key, browser_screenshot, browser_snapshot, browser_run_js, browser_sessions, browser_clear_domain
• Available via genesis-health MCP (always loaded, ~800 chars token cost)
• Browser launches lazily on first navigation — zero overhead until used
• All blocking tools have a hard 60s timeout (configurable per tool) to prevent indefinite hangs. browser_fill scales with string length.
• Default mode: Camoufox (anti-detection Firefox). Always runs headed on VNC display :99 — observable via noVNC. Profile at ~/.genesis/camoufox-profile/. Includes humanized cursor movement, per-keystroke typing with IKI jitter, and stealth click with hover/jitter.
• Chromium fallback: browser_navigate(url, stealth=False) uses Chromium for sites incompatible with Camoufox (rare). Profile at ~/.genesis/browser-profile/.
• Agent-owned accounts: log into accounts created FOR the agent, never the user's personal accounts. Treat the agent like a new employee.
• Collaborate mode: browser_collaborate(enable=True) switches to fast timing (0.5-2s delays vs 1-15s stealth). The browser is ALWAYS visible on VNC — no mode switch or restart needed. Use when a human is actively watching to speed up interaction. Disabling restores stealth timing.

Layer 3: Remote CDP (user's real Chrome over Tailscale)

• Tool: browser_navigate(url, remote=True) — built into genesis-health MCP
• Connects to user's Chrome via playwright.chromium.connect_over_cdp()
• Real browser, real fingerprint — nothing to detect. Bulletproof for ATS submissions with reCAPTCHA v3 or aggressive anti-bot detection.
• Collaborate timing auto-enabled (user watching their own screen)
• Drift detection: warns if user navigated away since last Genesis action
• User setup: Launch Chrome with --remote-debugging-port=9222 --user-data-dir=%USERPROFILE%\chrome-genesis (Windows batch file)
• Set GENESIS_CDP_URL=http://<tailscale-ip>:9222 in secrets.env, or pass cdp_url= parameter directly
• Graceful errors when Chrome is offline — no retry storms
• Camoufox stays default for non-adversarial browsing

Layer 3b: On-Demand MCP (network inspection — activate when needed)

• Tools: Chrome DevTools MCP (29 tools) or Playwright MCP
• Activate: /activate-browser → adds to .mcp.json → restart session
• Deactivate when done to reclaim ~17k tokens of context budget
• Use when you need network inspection, Lighthouse, or performance tracing beyond what the built-in Genesis browser tools provide

Layer 4: Computer Use (visual fallback — V4)

• Claude Computer Use API (screenshot-based interaction)
• ~1000 tokens per screenshot, expensive but universal
• Not yet implemented

Layer Selection Guide

When to Use

• Any task requiring interaction with a web page beyond simple fetching.
• Form filling, multi-step workflows, authenticated sessions.
• Data extraction requiring JavaScript rendering.
• Browser-based testing or verification.

Selector Strategy

Try selectors in this priority order:

Common patterns:

# Forms
input[name="username"]
input[type="password"]
button[type="submit"]
select[name="country"]
textarea[name="message"]

# Navigation
nav a[href="/dashboard"]
header .menu-item
a:has-text("About")

# E-commerce
.product-card .price
button:has-text("Add to Cart")
.cart-total

Error Recovery

Form Filling Workflow

1. Read page — Take snapshot to understand form structure
2. Identify fields — Map each required field to a selector
3. Fill sequentially — One field at a time, verify each
4. Handle dropdowns — Use select_option for <select>, click+text for custom dropdowns
5. Handle checkboxes — Click to toggle, verify state after
6. Screenshot before submit — Visual verification before irreversible action
7. Submit — Click submit button
8. Verify result — Read resulting page to confirm success

Safety Gates

MANDATORY before any financial transaction:

1. Summarize what will be purchased/paid
2. Show total cost
3. Get explicit user confirmation
4. Never auto-complete purchases
5. Never click "Place Order", "Pay Now", "Confirm Purchase" without approval

MANDATORY for credential entry:

1. Verify the domain is correct (check URL bar, not page content)
2. Warn on HTTP (non-HTTPS) credential pages
3. Never store passwords
4. Never enter credentials on unfamiliar domains without user confirmation

Session Management

• Browser sessions persist within a task/conversation
• Cookies and login state are maintained across page navigations
• Close browser explicitly when done to free resources
• If session needs to survive across tasks, document the auth state needed

Multi-Step Workflow Pattern

For complex workflows (e.g., fill form → verify → submit → navigate → extract):

1. Plan the steps — List all pages and actions before starting
2. Checkpoint after each page — Take snapshot, verify you're in the right place
3. Handle branching — If the workflow can branch (success/error), plan for both
4. Limit scope — Max 10-20 page navigations per task to prevent runaway browsing
5. Report progress — Log each completed step

Output Format

task_id: <BROWSER-YYYY-MM-DD-NNN>
pages_visited: <count>
actions_taken:
  - action: <navigate | click | type | select | screenshot>
    target: <selector or URL>
    result: <success | failed | recovered>
errors_recovered: <count>
screenshots: [<file paths>]
result: <task outcome description>

References

• Genesis browser MCP tools: browser_navigate, browser_click, browser_fill, browser_upload, browser_press_key, browser_screenshot, browser_snapshot, browser_run_js, browser_sessions, browser_clear_domain, browser_collaborate (via genesis-health MCP)
• src/genesis/mcp/health/browser.py — MCP tool implementations
• src/genesis/browser/profile.py — BrowserProfileManager (cookie DB, sessions)
• scripts/browser.py — Standalone CLI (opens/closes per command, for one-off use)
• src/genesis/skills/osint/SKILL.md — For web-based investigation
• /activate-browser command — On-demand Chrome DevTools MCP activation