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

Need	Layer	Why
Read a public page	Fetch	No login needed
Search the web	Fetch	API-based, fast
Fill a form on agent's account	Genesis Browser	Persistent login
Site blocks automation	Genesis Browser (stealth)	Anti-detection
CAPTCHA / payment / 2FA step	Genesis Browser (collaborate)	User takes VNC control
ATS with reCAPTCHA v3 / Ashby	Remote CDP	Real Chrome fingerprint
Submit on user's logged-in site	Remote CDP	User's sessions
Network inspection / Lighthouse	On-Demand MCP	Chrome DevTools
Take action in user's banking app	Remote CDP	MUST confirm

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:

Priority	Selector Type	Example	When
1	ID	#submit-btn	Element has unique ID
2	data-testid	[data-testid="login"]	Modern apps with test attributes
3	name attribute	input[name="email"]	Form fields
4	type attribute	input[type="submit"]	Standard form elements
5	Specific class	.btn-primary	Semantic class names
6	Visible text	text="Sign In"	Buttons and links
7	Composite	form.login input[type="email"]	When simple selectors aren't unique

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

Error	Recovery Steps
Element not found	1. Try alternative selector 2. Try visible text 3. Scroll page 4. Wait for dynamic load
Page timeout	1. Retry navigation 2. Check if URL redirected 3. Verify network connectivity
Login required	Inform user. Ask for credentials. Never guess passwords.
CAPTCHA	Switch to collaborate mode. User solves via VNC. Resume automation after.
Pop-up / modal	Click dismiss/close button. Look for [aria-label="Close"] or .modal-close
Cookie consent	Click "Accept" or dismiss. Look for #cookie-accept or text="Accept All"
Rate limited	Wait 30 seconds. Retry once. If still limited, back off exponentially.
Wrong page	Use page snapshot to verify. Navigate back. Check URL.
Stale element	Re-query the selector. Page may have re-rendered.

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