browser

name: browser description: Browser automation SOP — choose local Playwright (free) vs Browserbase cloud (metered), with session patterns and hand-off protocol. Use when a task requires web browsing. user-invocable: false

Browser Automation

Operational guide for web browsing tasks. Two browser options are available — choose the right one for the job.

See also: reference.md for detailed API reference, troubleshooting, credentials, and plan limits.

Decision Matrix

Option A: Local Playwright (MCP tools) — FREE, unlimited

The Playwright MCP server provides mcp__playwright__browser_* tools directly in the session.

Use when:

• Reading public web content (docs, articles, search results, prices)
• Simple scraping of public data
• Form fills on sites without bot protection
• Development/testing (previewing pages, checking our apps)
• Quick lookups (weather, reference, public info)
• Any site that doesn't actively block automation

Limitations:

• Detectable as headless browser (no stealth mode)
• No CAPTCHA auto-solving
• No human hand-off capability
• No persistent cookies across sessions
• Blocked by Cloudflare, aggressive anti-bot, headless detection

Pattern:

1. mcp__playwright__browser_navigate → go to URL
2. mcp__playwright__browser_snapshot → get page accessibility tree (preferred over screenshot for actions)
3. mcp__playwright__browser_click/type/etc → interact
4. mcp__playwright__browser_take_screenshot → visual capture when needed
5. mcp__playwright__browser_close → clean up when done

Option B: Browserbase Cloud (sidecar on port 3849) — METERED

Remote Chrome with stealth mode, CAPTCHA solving, human hand-off, and /session/eval for efficient form filling via page.evaluate().

Use when:

• Site requires authentication (human enters credentials via hand-off)
• Anti-bot protection present (Cloudflare, reCAPTCHA, headless detection)
• Banking & financial sites (need stealth + security)
• Utility account management (bill pay, account changes)
• CAPTCHA-gated workflows
• Need persistent cookies across sessions (context persistence)
• Form filling tasks — /session/eval enables batch-filling all fields in one call

Pattern:

1. POST http://localhost:3849/session/start { "url": "...", "contextName": "sitename" }
2. POST /session/eval — discover fields, batch-fill forms (see Form Filling Protocol)
3. POST /session/navigate, /session/click, /session/type — interact as needed
4. GET /session/screenshot — visual check
5. If blocked → hand off to human (see Hand-Off below)
6. POST /session/stop { "saveContext": true } — clean up, save cookies

Decision Flowchart

Is there an API, CLI tool, or curl option?
  YES → Use that (no browser needed)
  NO ↓

Is the content public with no bot protection?
  YES → Local Playwright (free)
  NO ↓

Anti-bot protection, CAPTCHA, or headless detection?
  YES → Browserbase
  NO ↓

Need human to enter credentials or approve something?
  YES → Browserbase (hand-off)
  NO ↓

Need to fill forms on a site with bot protection?
  YES → Browserbase (/session/eval for efficient batch fill)
  NO ↓

Need persistent cookies across sessions?
  YES → Browserbase (context persistence)
  NO → Local Playwright (free)

Hand-Off Protocol (Browserbase only)

When the assistant hits a blocker (CAPTCHA, login, MFA, payment approval):

1. Take screenshot, assess the blocker
2. Start hand-off: POST http://localhost:3847/browser/handoff/start
3. Get session info: GET http://localhost:3849/session/status → extract wrapperPath
4. Build the public hand-off URL: https://yourdomain.com{wrapperPath}
   • IMPORTANT: Always use your configured public domain URL, NEVER localhost — the human is on their phone/laptop, not on this machine
   • The daemon proxies /handoff/* to the sidecar automatically
5. Message human on the active channel with:
   • Hand-off URL (tappable link to the interactive web UI)
   • Screenshot of current page
   • Clear description: "I'm stuck on [X] — need you to [Y]"
   • Always include the available commands (see below)
6. Human interacts via the web UI or channel commands:
   • type: [text] — types into focused field (NEVER logged — safe for passwords)
   • screenshot — sends fresh screenshot
   • done / all yours — completes hand-off (shows confirmation overlay in web UI)
   • abort — cancels and closes session
7. Done confirmation: When the human taps Done in the web UI, a confirmation overlay appears asking them to confirm. This prevents accidental hand-back while still interacting.
8. Assistant resumes autonomous navigation after done is confirmed

Hand-Off Message Template

Always include this in the initial hand-off message to the human:

I need your help with [description of blocker].

Hand-off page: https://yourdomain.com/handoff/page?token=TOKEN_HERE

[Description of what's on screen and what you need them to do]

Available commands:
• type: [text] — type into the focused field
• screenshot — get a fresh screenshot
• done — hand control back to me
• abort — cancel and close the session

Hand-Off Triggers

• CAPTCHA that auto-solve can't handle
• Login requiring credentials the assistant doesn't have
• Multi-factor authentication (phone/email codes, authenticator)
• "Are you human?" challenges
• Payment confirmation (human must explicitly approve)
• Anything the assistant can't figure out from screenshots

Form Filling Protocol (Browserbase)

When filling forms via Browserbase, follow this efficient workflow:

1. Navigate to the Form Page

curl -s -X POST http://localhost:3849/session/start \
  -H 'Content-Type: application/json' \
  -d '{"url": "https://example.com/application", "contextName": "sitename"}'

2. Discover All Form Fields

Use /session/eval to enumerate every field on the page:

curl -s -X POST http://localhost:3849/session/eval \
  -H 'Content-Type: application/json' \
  -d '{"script": "Array.from(document.querySelectorAll(\"input, select, textarea\")).map(el => ({tag: el.tagName, type: el.type, name: el.name, id: el.id, label: el.labels?.[0]?.textContent?.trim() || null, options: el.tagName===\"SELECT\" ? Array.from(el.options).map(o=>({val:o.value,text:o.text})) : undefined})).filter(f => f.type !== \"hidden\" && f.name !== \"\")"}'

For complex discovery scripts, use Python to avoid escaping issues (see reference.md for the Python eval helper pattern).

3. Batch-Fill All Fields in One Call

Use /session/eval with the React-compatible native setter pattern:

# Use Python for the actual call — much cleaner than curl with escaped JSON
python3 -c "
import json, subprocess
script = '''(() => {
  const setter = Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, 'value').set;
  const fields = {'firstName': 'John', 'lastName': 'Smith', 'email': 'john@example.com'};
  for (const [id, val] of Object.entries(fields)) {
    const el = document.getElementById(id);
    if (el) { setter.call(el, val); el.dispatchEvent(new Event('input', {bubbles:true})); el.dispatchEvent(new Event('change', {bubbles:true})); }
  }
  return 'filled';
})()'''
r = subprocess.run(['curl', '-s', '-X', 'POST', 'http://localhost:3849/session/eval',
  '-H', 'Content-Type: application/json', '-d', json.dumps({'script': script})],
  capture_output=True, text=True)
print(r.stdout)
"

4. Screenshot to Verify

curl -s http://localhost:3849/session/screenshot > /tmp/form-filled.png

Review the screenshot to confirm all fields are populated correctly.

5. Submit or Hand Off

• If the form is ready: use /session/click to submit
• If there is a CAPTCHA or login blocker: hand off to human (see Hand-Off Protocol)
• If the human needs to review before submitting: hand off with instructions to review and click Submit

Tips

• Use Python for eval scripts: Shell escaping of JSON containing JavaScript is error-prone. Python's json.dumps() handles it cleanly.
• Session timeout is 300s by default: For multi-page forms, work quickly. You can set SESSION_TIMEOUT env var on the sidecar for longer workflows.
• Discover before filling: Never guess field IDs. Always run the discovery script first. Field IDs vary wildly across sites.
• Dropdowns need separate handling: Native <select> uses .value + change event. Custom dropdowns (React Select, etc.) need click-based interaction via /session/click.
• Masked fields need /session/type: For SSN, phone, credit card fields with input masks, use /session/type with the field selector instead of eval. Masks rely on keystroke events.
• Government sites: Watch for ASP.NET postbacks (dropdown changes reload the page), aggressive session timeouts, and CAPTCHA on submission. See reference.md for detailed tips.

Security Rules

1. type: relay text is NEVER logged — passwords, SSNs, account numbers are safe
2. Live view URLs only sent via private channel DM — never in group chats or logs
3. Financial transactions require explicit human approval
4. Session recording is OFF — no video of banking/password screens on Browserbase servers
5. Proxy providers block banking domains — hand-off to human is the approach for those

Site Knowledge (Memory-Based)

Per-site learnings (field selectors, navigation flows, quirks, anti-bot patterns) are stored as memories in .kithkit/state/memory/memories/, NOT in this skill. This keeps the skill shareable without leaking site-specific knowledge.

Before Browsing: Look Up What You Know

Before interacting with any site, check memory for prior learnings:

# Search by domain
Grep "egov.maryland.gov" path=".kithkit/state/memory/memories/"

# Search by category
Grep "category: website" path=".kithkit/state/memory/memories/"

# Search by tag
Grep "tags:.*md-business-express" path=".kithkit/state/memory/memories/"

If you find a matching memory, read it. It may contain field IDs, navigation steps, known quirks, or auth requirements that save you from re-discovering everything.

After Browsing: Capture What You Learned

When you discover something useful about a site, store it immediately using /memory add:

Memory format for website learnings:

---
date: 2026-02-11T21:00:00
category: website
importance: medium
subject: egov.maryland.gov — LLC Filing Form
tags: [maryland, business-express, llc, government, form-filling]
confidence: 0.9
source: observation
---

# egov.maryland.gov — LLC Filing Form

## Access
- URL: https://egov.maryland.gov/BusinessExpress
- Auth: account required (credential-md-business-express-username)
- Anti-bot: minimal (no Cloudflare, no CAPTCHA on forms)
- Browser: Browserbase recommended (account login required)

## Navigation
- Register LLC: Dashboard → Register → Maryland Limited Liability Company → "Use Online Forms"
- 6-step wizard: Business Name → Business Info → Resident Agent → Additional → Confirm → Pay

## Form Fields (Step 1 — Business Name)
- `#BusinessSuffix`: select, options: ", LLC" / ", L.L.C." / ", Limited Liability Company"
- `#BusinessName`: input, the LLC name without suffix
- Availability check button: `#btnCheckAvailability`

## Quirks
- Dropdown changes trigger ASP.NET postbacks (full page reload)
- County dropdown populates after state selection — wait for reload
- Session timeout: aggressive, ~15 min idle

What to Capture

Staleness & Verification

Site knowledge can go stale (redesigns, updated field IDs). Handle this with verify-on-use:

1. Try the stored knowledge — use remembered selectors/flows
2. If it fails — re-discover (run field enumeration, take screenshots)
3. Update the memory — correct the stale data immediately
4. Note the last verified date in the memory content

Don't preemptively invalidate — trust stored knowledge until it actually fails.

Naming Convention

Website memory files follow the standard memory naming:

YYYYMMDD-HHMM-site-slug.md

Examples:

• 20260211-2100-egov-maryland-llc-filing.md
• 20260212-1400-chase-bank-login.md
• 20260213-0900-irs-ein-application.md

Sharing

This skill (SKILL.md, reference.md) can be shared upstream or with peers. Per-site memories stay in each agent's private .kithkit/state/memory/memories/ directory. An agent receiving this skill will build their own site knowledge through use.

Cost Awareness

• Budget: 100 hours/month ($0.12/hr overage)
• Typical task: 2-5 minutes (login, navigate, grab data)
• At 5 min/task: budget supports ~1,200 tasks/month
• Proxy bandwidth: 1 GB/month — avoid large file downloads through Browserbase
• When in doubt: prefer local Playwright for anything that doesn't need stealth/auth

References

• reference.md — Detailed API reference, session lifecycle, troubleshooting, credentials, plan limits